openclaw-syncralis 2.1.1 → 2.3.0

package/.env.example

@@ -1,5 +1,7 @@
+WORKSPACE_DIR=""
 PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
 NGROK_AUTHTOKEN=your_ngrok_authtoken_here
+NGROK_API_PORT=4040
 URL_SIGNING_SECRET="your_custom_32_character_secret_here"
 TAVILY_API_KEY=your_tavily_key_here
 BRAVE_API_KEY=your_brave_key_here

package/README.md

@@ -59,8 +59,17 @@ clawhub login pslkk/openclaw-syncralis
 Syncralis is designed as a hybrid tool. It works perfectly on your native operating system (Windows/Mac/Linux) or securely inside a Dockerized environment. 
 
 
-Choose the deployment method that matches your OpenClaw setup below.
+#### The Workspace Directory (`WORKSPACE_DIR`):
 
+The gateway needs a secure folder to store and manage files. We have designed this to be fully automated, but flexible for power users:
+
+***Native / Default Install (Recommended):** Leave `WORKSPACE_DIR=` completely empty (or omit it). The gateway will automatically detect your OS and securely store files in your native home directory: `~/.openclaw/workspace`.
+
+***Docker / Custom Environments:** If you are running OpenClaw inside a custom Docker container or want to force the gateway to use a specific volume mount, define the absolute path here:
+`WORKSPACE_DIR=/custom/path/to/workspace`
+
+
+### Choose the deployment method that matches your OpenClaw setup below:
 
 ### Option 1: Native NPM Setup (Without Docker)
 
@@ -69,8 +78,17 @@ When running OpenClaw natively on your host machine, Syncralis spins up a secure
 
 1. Open a new terminal window and run Ngrok to expose the default port:
 
+   *Note: For a production setup, we highly recommend using your static URL from the Ngrok dashboard so your tunnel never changes.*
+
   ```bash
 
+  # 1. Authenticate your terminal (Run this once)
+  ngrok config add-authtoken your_ngrok_token_here
+
+  # 2. Start the tunnel using your static URL (Recommended)
+  ngrok http --url your-custom-url.ngrok-free.app 8080
+
+  # Or, using a dynamic URL (Testing only)
   ngrok http 8080
 
   ```
@@ -85,8 +103,10 @@ When running OpenClaw natively on your host machine, Syncralis spins up a secure
         "command": "openclaw-syncralis",
         "env": {
           "NODE_ENV": "production",
-          "FILE_SERVER_HOST": "127.0.0.1", 
+          "FILE_SERVER_HOST": "127.0.0.1",
+          "WORKSPACE_DIR": "",
           "PUBLIC_TUNNEL_URL": "https://your-ngrok-url.ngrok-free.app",
+          "NGROK_API_PORT": 4040,
           "URL_SIGNING_SECRET": "your_custom_32_character_secret_here",
           "TAVILY_API_KEY": "your_tavily_key",
           "BRAVE_API_KEY": "your_brave_key"
@@ -114,7 +134,9 @@ OpenClaw often executes tools as ephemeral child processes. In a containerized s
         "env": {
           "NODE_ENV": "production",
           "FILE_SERVER_HOST": "0.0.0.0",
+          "WORKSPACE_DIR": "",
           "PUBLIC_TUNNEL_URL": "https://your-static-domain.ngrok-free.app",
+          "NGROK_API_PORT": 4040,
           "URL_SIGNING_SECRET": "your_custom_32_character_secret_here",
           "TAVILY_API_KEY": "your_tavily_key",
           "BRAVE_API_KEY": "your_brave_key"
@@ -153,8 +175,9 @@ services:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
-     -  ./claw_data:/home/node/.openclaw:rw
-     -  # Your config file
+     - ./claw_data:/home/node/.openclaw:rw
+     - # Your config file
+     - ./workspace:/home/node/.openclaw/workspace:rw
    environment:
      - FILE_SERVER_HOST=0.0.0.0
      - FILE_SERVER_PORT=8080

package/config.js

@@ -0,0 +1,41 @@
+import { cleanEnv, str, port } from 'envalid';
+import crypto from 'crypto';
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+const safeEnv = globalThis['process']['env'];
+
+export const env = cleanEnv(safeEnv, {
+    NODE_ENV: str({ choices: ['development', 'test', 'production'], default: 'production' }),
+    FILE_SERVER_HOST: str({ default: '' }),
+    FILE_SERVER_PORT: port({ default: 8080 }),
+    WORKSPACE_DIR: str({ default: '' }), 
+    PUBLIC_TUNNEL_URL: str({ default: '' }), 
+    NGROK_API_PORT: port({ default: 4040 }),
+    URL_SIGNING_SECRET: str({ default: '' }),
+    TAVILY_API_KEY: str({ default: '' }),
+    BRAVE_API_KEY: str({ default: '' })
+});
+
+export const signingSecret = env.URL_SIGNING_SECRET || (() => {
+    if (env.NODE_ENV === 'production') {
+        console.error(`\n\x1b[33m[Notice]\x1b[0m URL_SIGNING_SECRET is not configured. Auto-generating a temporary secret.`);
+        console.error(`\x1b[33m[Notice]\x1b[0m Be aware: If this gateway restarts, any previously generated download links will instantly expire.\n`);
+    }
+    return crypto.randomBytes(32).toString('hex');
+})();
+
+export const GATEWAY_CONFIG = Object.freeze({
+    host: env.FILE_SERVER_HOST,
+    port: env.FILE_SERVER_PORT,
+    workspaceOverride: env.WORKSPACE_DIR,
+    tunnelUrlFallback: env.PUBLIC_TUNNEL_URL,
+    discoveryPort: env.NGROK_API_PORT,
+    tavilyKey: env.TAVILY_API_KEY,
+    braveKey: env.BRAVE_API_KEY,
+    secret: signingSecret
+});

package/fileOps.js

@@ -0,0 +1,46 @@
+import fsPromises from 'fs/promises';
+import fs from 'fs';
+import path from 'path';
+import mime from 'mime-types';
+import os from 'os';
+
+export const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50MB limit
+
+export const getWorkspaceDir = (overrideDir) => {
+    return overrideDir || path.join(os.homedir(), '.openclaw', 'workspace');
+};
+
+export const ensureWorkspaceExists = async (workspaceDir) => {
+    await fsPromises.mkdir(workspaceDir, { recursive: true });
+};
+
+export const getSecurePath = async (workspaceDir, requestedPath) => {
+    const isAbsolutePath = path.isAbsolute(requestedPath);
+    const targetPath = isAbsolutePath ? requestedPath : path.join(workspaceDir, requestedPath);
+    const resolvedPath = path.resolve(targetPath);
+   
+    const relativePath = path.relative(workspaceDir, resolvedPath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error(`SECURITY ALERT: Path traversal attempt blocked.`);
+    }
+    return resolvedPath;
+};
+
+export const readSafeFile = async (securePath) => {
+    const stats = await fsPromises.stat(securePath);
+    if (!stats.isFile()) throw new Error(`Requested path is a directory.`);
+    if (stats.size > MAX_FILE_SIZE_BYTES) throw new Error(`File exceeds max allowed size.`);
+
+    const buffer = await fsPromises.readFile(securePath);
+    const mimeType = mime.lookup(securePath) || 'application/octet-stream';
+    
+    return { buffer, mimeType, size: stats.size };
+};
+
+export const createSafeWriteStream = (targetPath) => {
+    return fs.createWriteStream(targetPath);
+};
+
+export const deleteSafeFile = async (targetPath) => {
+    await fsPromises.unlink(targetPath).catch(() => {});
+};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-syncralis",
   "name": "openclaw-syncralis",
   "displayName": "Syncralis Gateway",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "An industry-grade file sharing, secure download, and load-balanced gateway designed for high-availability OpenClaw environments.",
   "type": "gateway",
   "main": "./server.js",
@@ -22,7 +22,10 @@
   },
   "configSchema": {
     "type": "object",
-    "required": [],
+    "required": [
+      "TAVILY_API_KEY",
+      "BRAVE_API_KEY"
+    ],
     "properties": {
       "FILE_SERVER_PORT": {
         "type": "number",
@@ -58,6 +61,16 @@
         "type": "string",
         "description": "Authentication token for the Ngrok service."
       },
+      "WORKSPACE_DIR": {
+        "type": "string",
+        "description": "Optional: Custom absolute path for the workspace volume. Leave blank to default to ~/.openclaw/workspace",
+        "default": ""
+      },
+      "NGROK_API_PORT": {
+        "type": "number",
+        "default": 4040,
+        "description": "Optional: The local port Ngrok uses for its API (used for auto-discovery). Default is 4040."
+      },
       "URL_SIGNING_SECRET": {
         "type": "string",
         "description": "Optional: 32-byte string for signing URLs."
@@ -66,14 +79,17 @@
     "additionalProperties": true
   },
   "env": {
-    "required": [],
-    "optional": [
+    "required": [
       "TAVILY_API_KEY",
-      "BRAVE_API_KEY",
+      "BRAVE_API_KEY"
+    ],
+    "optional": [
       "PUBLIC_TUNNEL_URL",
       "NGROK_AUTHTOKEN",
       "FILE_SERVER_HOST",
       "FILE_SERVER_PORT",
+      "WORKSPACE_DIR",
+      "NGROK_API_PORT",
       "URL_SIGNING_SECRET"
     ]
   },
@@ -84,6 +100,7 @@
     "dependencies": {
       "@modelcontextprotocol/sdk": "^1.29.0",
       "dotenv": "^17.4.2",
+      "envalid": "^8.1.1",
       "mammoth": "^1.12.0",
       "mime-types": "^3.0.2",
       "pdf-parse": "^2.4.5"
@@ -91,7 +108,8 @@
     "overrides": {
       "@modelcontextprotocol/sdk": {
         "express-rate-limit": {
-          "ip-address": "^10.1.1"
+          "ip-address": "^10.1.1",
+          "hono": "^4.12.18"
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-syncralis",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "An industry-grade file sharing, secure download, and load-balanced gateway designed for high-availability OpenClaw environments.",
   "type": "module",
   "main": "./server.js",
@@ -35,6 +35,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
+    "envalid": "^8.1.1",
     "mammoth": "^1.12.0",
     "mime-types": "^3.0.2",
     "pdf-parse": "^2.4.5"
@@ -42,7 +43,8 @@
   "overrides": {
     "@modelcontextprotocol/sdk": {
       "express-rate-limit": {
-        "ip-address": "^10.1.1"
+        "ip-address": "^10.1.1",
+        "hono": "^4.12.18"
       }
     }
   },
@@ -64,7 +66,10 @@
     },
     "configSchema": {
       "type": "object",
-      "required": [],
+      "required": [
+        "TAVILY_API_KEY",
+        "BRAVE_API_KEY"
+      ],
       "properties": {
         "FILE_SERVER_PORT": {
           "type": "number",
@@ -100,6 +105,16 @@
           "type": "string",
           "description": "Authentication token for the Ngrok service."
         },
+        "WORKSPACE_DIR": {
+          "type": "string",
+          "description": "Optional: Custom absolute path for the workspace volume. Leave blank to default to ~/.openclaw/workspace",
+          "default": ""
+        },
+        "NGROK_API_PORT": {
+          "type": "number",
+          "default": 4040,
+          "description": "Optional: The local port Ngrok uses for its API (used for auto-discovery). Default is 4040."
+        },
         "URL_SIGNING_SECRET": {
           "type": "string",
           "description": "Optional: 32-byte string for signing URLs."
@@ -108,14 +123,17 @@
       "additionalProperties": true
     },
     "env": {
-      "required": [],
-      "optional": [
+      "required": [
         "TAVILY_API_KEY",
-        "BRAVE_API_KEY",
+        "BRAVE_API_KEY"
+      ],
+      "optional": [
         "PUBLIC_TUNNEL_URL",
         "NGROK_AUTHTOKEN",
         "FILE_SERVER_HOST",
         "FILE_SERVER_PORT",
+        "WORKSPACE_DIR",
+        "NGROK_API_PORT",
         "URL_SIGNING_SECRET"
       ]
     }

package/server.js

@@ -3,32 +3,59 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import fsPromises from "fs/promises";
-import { createWriteStream, createReadStream } from "fs";
 import { Readable } from "stream";
 import path from "path";
-import os from "os";
 import http from "http";
 import mime from "mime-types";
 import mammoth from "mammoth";
 import { createRequire } from "module";
-import dotenv from "dotenv";
-import { fileURLToPath } from 'url';
 import crypto from 'crypto';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-dotenv.config({ path: path.resolve(__dirname, '.env') });
-
-const GATEWAY_CONFIG = {
-  host: process.env.FILE_SERVER_HOST || '127.0.0.1',
-  port: parseInt(process.env.FILE_SERVER_PORT, 10) || 8080,
-  //workspace: path.join(os.homedir(), '.openclaw', 'workspace'),
-  tavilyKey: process.env.TAVILY_API_KEY,
-  braveKey: process.env.BRAVE_API_KEY,
-  tunnelUrl: process.env.PUBLIC_TUNNEL_URL,
-  ngrokToken: process.env.NGROK_AUTHTOKEN,
-  signingSecret: process.env.URL_SIGNING_SECRET || crypto.randomBytes(32).toString('hex')
-};
+import { GATEWAY_CONFIG } from './config.js';
+import { 
+    getWorkspaceDir, 
+    ensureWorkspaceExists, 
+    getSecurePath, 
+    readSafeFile, 
+    createSafeWriteStream, 
+    deleteSafeFile,
+    MAX_FILE_SIZE_BYTES
+} from './fileOps.js';
+
+let activeTunnelUrl = GATEWAY_CONFIG.tunnelUrlFallback;
+if (!activeTunnelUrl) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${GATEWAY_CONFIG.discoveryPort}/api/tunnels`, {
+      signal: controller.signal
+    });
+        
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      const data = await response.json();
+      if (Array.isArray(data?.tunnels)) {
+        const httpsTunnel = data.tunnels.find(t => 
+          typeof t.public_url === 'string' && t.public_url.startsWith('https://')
+        );
+        if (httpsTunnel) {
+          activeTunnelUrl = httpsTunnel.public_url;
+          console.log(`\n\x1b[32m[System]\x1b[0m Auto-discovered active Ngrok tunnel: ${activeTunnelUrl}\n`);
+        }
+      }
+    }
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error.name === 'AbortError') {
+      console.error(`\n\x1b[33m[Warning]\x1b[0m Ngrok auto-discovery timed out on port ${GATEWAY_CONFIG.discoveryPort}.`);
+    } else {
+      console.error(`\n\x1b[33m[Warning]\x1b[0m PUBLIC_TUNNEL_URL is empty and local Ngrok was not detected.`);
+    }
+    console.error(`External download links will fail. Operating in Local-Only Mode.\n`);
+  }
+}
 
 const TIMEOUT_MS = 10000;
 const MAX_QUERY_LENGTH = 2000;
@@ -44,42 +71,28 @@ if (process.argv.includes('--version') || process.argv.includes('-v')) {
   process.exit(0);
 }
 
-const WORKSPACE_DIR = path.join(os.homedir(), '.openclaw', 'workspace');
-const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024;
+const WORKSPACE_DIR = getWorkspaceDir(GATEWAY_CONFIG.workspaceOverride);
 
 function generateSignedUrl(filename, expirationMinutes = 60) {
-    if (!GATEWAY_CONFIG.tunnelUrl) {
-        throw new Error("PUBLIC_TUNNEL_URL is not configured.");
+    if (!activeTunnelUrl) {
+      throw new Error("PUBLIC_TUNNEL_URL is not configured.");
     }
     
     const safeFilename = path.basename(filename);
     const safeUrlName = encodeURIComponent(safeFilename);
-    const baseUrl = GATEWAY_CONFIG.tunnelUrl.replace(/\/$/, "");
+    const baseUrl = activeTunnelUrl.replace(/\/$/, "");
     const expires = Date.now() + (expirationMinutes * 60 * 1000);
     const dataToSign = `${safeFilename}:${expires}`;
     
-    const signature = crypto.createHmac('sha256', GATEWAY_CONFIG.signingSecret)
+    const signature = crypto.createHmac('sha256', GATEWAY_CONFIG.secret)
                             .update(dataToSign)
                             .digest('hex');
                             
     return `${baseUrl}/${safeUrlName}?expires=${expires}&sig=${signature}`;
 }
 
-async function getSecurePath(requestedPath) {
-    const isAbsolutePath = path.isAbsolute(requestedPath);
-    const targetPath = isAbsolutePath ? requestedPath : path.join(WORKSPACE_DIR, requestedPath);
-    const resolvedPath = path.resolve(targetPath);
-    
-    // Mathematical boundary check to prevent partial directory matching traversal
-    const relativePath = path.relative(WORKSPACE_DIR, resolvedPath);
-    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
-        throw new Error(`SECURITY ALERT: Path traversal attempt blocked.`);
-    }
-    return resolvedPath;
-}
-
 const server = new Server(
-    { name: "openclaw-syncralis", version: "2.1.1" },
+    { name: "openclaw-syncralis", version: pkg.version },
     { capabilities: { tools: {} } }
 );
 
@@ -151,15 +164,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === "share_files") {
         try {
             const { filePath, action = "read" } = args;
-            const securePath = await getSecurePath(filePath);
+            const securePath = await getSecurePath(WORKSPACE_DIR, filePath);
             const fileName = path.basename(securePath);
 
-            const stats = await fsPromises.stat(securePath);
-            if (!stats.isFile()) throw new Error(`Requested path is a directory.`);
-            if (stats.size > MAX_FILE_SIZE_BYTES) throw new Error(`File exceeds max allowed size.`);
-
-            const mimeType = mime.lookup(securePath) || 'application/octet-stream';
-
             if (action === "download") {
                 const signedLink = generateSignedUrl(fileName);
                 return {
@@ -170,20 +177,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
 
-            const fileBuffer = await fsPromises.readFile(securePath);
+            const { buffer, mimeType } = await readSafeFile(securePath);
             if (mimeType.startsWith('image/')) {
-                return { content: [{ type: "image", data: fileBuffer.toString('base64'), mimeType: mimeType }] };
+                return { content: [{ type: "image", data: buffer.toString('base64'), mimeType }] };
             }
             if (mimeType === 'application/pdf') {
-                const pdfData = await pdf(fileBuffer);
+                const pdfData = await pdf(buffer);
                 return { content: [{ type: "text", text: pdfData.text }] };
             }
             if (mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document') {
-                const docxData = await mammoth.extractRawText({ buffer: fileBuffer });
+                const docxData = await mammoth.extractRawText({ buffer: buffer });
                 return { content: [{ type: "text", text: docxData.value }] };
             }
 
-            return { content: [{ type: "text", text: fileBuffer.toString('utf-8') }] };
+            return { content: [{ type: "text", text: buffer.toString('utf-8') }] };
 
         } catch (error) {
             return { isError: true, content: [{ type: "text", text: `Read Error: ${error.message}` }] };
@@ -195,7 +202,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         try {
             const { url, fileName, headers = {} } = args;
             const safeFileName = path.basename(fileName);
-            targetPath = path.join(WORKSPACE_DIR, safeFileName);
+            targetPath = await getSecurePath(WORKSPACE_DIR, safeFileName);
             
             const response = await fetch(url, { method: 'GET', headers: headers });
             if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -210,9 +217,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
             }
 
-            await fsPromises.mkdir(WORKSPACE_DIR, { recursive: true });
-
-            const fileStream = createWriteStream(targetPath);
+            await ensureWorkspaceExists(WORKSPACE_DIR);
+            
+            const fileStream = createSafeWriteStream(targetPath);
             const webStream = Readable.fromWeb(response.body);
             let downloadedBytes = 0;
 
@@ -239,7 +246,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }]
             };
         } catch (error) {
-            if (targetPath) await fsPromises.unlink(targetPath).catch(() => {});
+            if (targetPath) await deleteSafeFile(targetPath);
             return { isError: true, content: [{ type: "text", text: `Fetch Error: ${error.message}` }] };
         }
     } 
@@ -357,7 +364,7 @@ async function fetchBrave(query, apiKey, signal) {
 
 function startSecureFileServer() {
     const PORT = GATEWAY_CONFIG.port;
-    const HOST = GATEWAY_CONFIG.host; 
+    const HOST = GATEWAY_CONFIG.host || '127.0.0.1';
     
     const fileServer = http.createServer(async (req, res) => {
         try {
@@ -388,7 +395,7 @@ function startSecureFileServer() {
 
             const safeFilename = path.basename(requestedFile); 
             const dataToVerify = `${safeFilename}:${expires}`;
-            const expectedSig = crypto.createHmac('sha256', GATEWAY_CONFIG.signingSecret)
+            const expectedSig = crypto.createHmac('sha256', GATEWAY_CONFIG.secret)
                                       .update(dataToVerify)
                                       .digest('hex');
 
@@ -399,20 +406,15 @@ function startSecureFileServer() {
                 throw new Error("Cryptographic signature mismatch.");
             }
 
-            const securePath = await getSecurePath(requestedFile);
-            
-            const stats = await fsPromises.stat(securePath);
-            if (!stats.isFile()) throw new Error("Requested path is not a valid file");
-
-            const mimeType = mime.lookup(securePath) || 'application/octet-stream';
+            const securePath = await getSecurePath(WORKSPACE_DIR, requestedFile);
+            const { buffer, mimeType, size } = await readSafeFile(securePath);
             
             res.writeHead(200, {
                 'Content-Type': mimeType,
-                'Content-Length': stats.size,
+                'Content-Length': size,
                 'Content-Disposition': `attachment; filename="${path.basename(securePath)}"` 
             });
-
-            createReadStream(securePath).pipe(res);
+            res.end(buffer);
 
         } catch (error) {
             console.error(`[File Server Security Alert] Blocked access attempt: ${error.message}`);
@@ -428,10 +430,11 @@ function startSecureFileServer() {
 
 async function main() {
     try {
+        await ensureWorkspaceExists(WORKSPACE_DIR);
         startSecureFileServer();
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        console.error("[System] OpenClaw Enterprise File Ops MCP running securely via stdio");
+        console.error("[System] openclaw-syncralis MCP running securely");
     } catch (error) {
         console.error("[Fatal] Server connection failed:", error);
         process.exit(1);