Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: harden auto-start with strict localhost check and single-flight guard

Luigi Agosti2ac144f06b5c
diff --git a/plugin/README.md b/plugin/README.md
index bdcadcde..187fea87 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -11,14 +11,14 @@ openclaw gateway restart
## Quick Start
-The plugin auto-starts a local PinchTab server when needed. Just install and go:
+The plugin can auto-start a local PinchTab server when needed (`autoStart: true` by default). This only works when `baseUrl` points to a local address (`localhost`, `127.0.0.1`, or `::1`).
```bash
openclaw plugins install @pinchtab/pinchtab
openclaw gateway restart
```
-For remote servers or Docker, disable auto-start and set `baseUrl`.
+For remote servers or Docker, set `autoStart: false` and configure `baseUrl` manually.
## Configure
@@ -34,10 +34,12 @@ For remote servers or Docker, disable auto-start and set `baseUrl`.
token: "my-secret",
timeoutMs: 30000,
- // Startup (local only)
- autoStart: true, // auto-start server if not running
- binaryPath: "pinchtab", // path to binary
- startupTimeoutMs: 30000, // max wait for startup
+ // Auto-start (local only — localhost, 127.0.0.1, or ::1)
+ // When enabled, spawns a PinchTab server process if baseUrl
+ // points to a local address and the server is not running.
+ autoStart: true,
+ binaryPath: "pinchtab", // absolute path or binary name in PATH
+ startupTimeoutMs: 30000, // max wait for server to become ready
// Policy
allowEvaluate: false, // block JS evaluate by default
@@ -222,6 +224,7 @@ pinchtab({ action: "wait", text: "Welcome back", timeout: 120000 })
## Security Notes
+- **Auto-start** spawns a background process — only enabled for local addresses (`localhost`, `127.0.0.1`, `::1`). Set `autoStart: false` if you prefer explicit server management.
- **`evaluate`** is blocked by default (`allowEvaluate: false`) — enable only for trusted agents
- Use `allowedDomains` to restrict navigation (e.g., `["*.example.com"]`)
- Use `PINCHTAB_TOKEN` to gate API access; rotate regularly
diff --git a/plugin/session.test.ts b/plugin/session.test.ts
index 10ba1bb6..e6870250 100644
--- a/plugin/session.test.ts
+++ b/plugin/session.test.ts
@@ -1,6 +1,6 @@
import { describe, it, beforeEach } from "node:test";
import assert from "node:assert";
-import { getLastTabId, setLastTabId, resolveProfile } from "./session.ts";
+import { getLastTabId, setLastTabId, resolveProfile, isLocalHost } from "./session.ts";
describe("tab session state", () => {
beforeEach(() => {
@@ -63,3 +63,33 @@ describe("resolveProfile", () => {
assert.deepStrictEqual(result, { instanceId: "s1" });
});
});
+
+describe("isLocalHost", () => {
+ it("returns true for localhost", () => {
+ assert.strictEqual(isLocalHost("http://localhost:9867"), true);
+ assert.strictEqual(isLocalHost("http://localhost"), true);
+ assert.strictEqual(isLocalHost("http://LOCALHOST:9867"), true);
+ });
+
+ it("returns true for 127.0.0.1", () => {
+ assert.strictEqual(isLocalHost("http://127.0.0.1:9867"), true);
+ assert.strictEqual(isLocalHost("http://127.0.0.1"), true);
+ });
+
+ it("returns true for IPv6 localhost", () => {
+ assert.strictEqual(isLocalHost("http://[::1]:9867"), true);
+ assert.strictEqual(isLocalHost("http://[::1]"), true);
+ });
+
+ it("returns false for remote hosts", () => {
+ assert.strictEqual(isLocalHost("http://example.com"), false);
+ assert.strictEqual(isLocalHost("http://192.168.1.1:9867"), false);
+ assert.strictEqual(isLocalHost("http://pinchtab.local:9867"), false);
+ assert.strictEqual(isLocalHost("https://api.pinchtab.com"), false);
+ });
+
+ it("returns false for invalid URLs", () => {
+ assert.strictEqual(isLocalHost("not-a-url"), false);
+ assert.strictEqual(isLocalHost(""), false);
+ });
+});
diff --git a/plugin/session.ts b/plugin/session.ts
index 08b007a1..a033eadf 100644
--- a/plugin/session.ts
+++ b/plugin/session.ts
@@ -3,6 +3,17 @@ import { pinchtabFetch } from "./client.js";
let serverStarted = false;
let lastTabId: string | undefined;
+let startupPromise: Promise<{ ok: boolean; error?: string; autoStarted?: boolean }> | null = null;
+
+export function isLocalHost(baseUrl: string): boolean {
+ try {
+ const url = new URL(baseUrl);
+ const host = url.hostname.toLowerCase();
+ return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+ } catch {
+ return false;
+ }
+}
export function getLastTabId(): string | undefined {
return lastTabId;
@@ -56,20 +67,46 @@ export async function getEnhancedHealth(cfg: PluginConfig): Promise<any> {
return result;
}
-export async function ensureServerRunning(cfg: PluginConfig): Promise<{ ok: boolean; error?: string }> {
+export async function ensureServerRunning(cfg: PluginConfig): Promise<{ ok: boolean; error?: string; autoStarted?: boolean }> {
const base = cfg.baseUrl || "http://localhost:9867";
- const isLocal = base.includes("localhost") || base.includes("127.0.0.1");
const healthCheck = await pinchtabFetch(cfg, "/health");
if (!healthCheck?.error) {
return { ok: true };
}
- if (!isLocal || cfg.autoStart === false || serverStarted) {
+ if (!isLocalHost(base) || cfg.autoStart === false || serverStarted) {
return { ok: false, error: healthCheck.error };
}
- const binary = cfg.binaryPath || "pinchtab";
+ // Single-flight guard: if startup is in progress, wait for it
+ if (startupPromise) {
+ return startupPromise;
+ }
+
+ startupPromise = doStartServer(cfg);
+ try {
+ return await startupPromise;
+ } finally {
+ startupPromise = null;
+ }
+}
+
+async function resolveBinaryPath(binary: string): Promise<string> {
+ if (binary.startsWith("/") || binary.startsWith("./")) {
+ return binary;
+ }
+ try {
+ const { execSync } = await import("child_process");
+ const resolved = execSync(`which ${binary}`, { encoding: "utf8" }).trim();
+ return resolved || binary;
+ } catch {
+ return binary;
+ }
+}
+
+async function doStartServer(cfg: PluginConfig): Promise<{ ok: boolean; error?: string; autoStarted?: boolean }> {
+ const binary = await resolveBinaryPath(cfg.binaryPath || "pinchtab");
const startupTimeout = cfg.startupTimeoutMs ?? 30000;
try {
@@ -86,7 +123,7 @@ export async function ensureServerRunning(cfg: PluginConfig): Promise<{ ok: bool
await new Promise((r) => setTimeout(r, 500));
const check = await pinchtabFetch(cfg, "/health");
if (!check?.error) {
- return { ok: true };
+ return { ok: true, autoStarted: true };
}
}
return { ok: false, error: `Server failed to start within ${startupTimeout}ms` };