@wolpertingerlabs/drawlatch 1.0.0-alpha.1 → 1.0.0-alpha.3

package/README.md

@@ -1,4 +1,6 @@
-# drawlatch
+# Drawlatch
+
+> **Alpha Software:** This project is in alpha. Expect breaking changes between updates.
 
 A config-driven MCP (Model Context Protocol) proxy that lets Claude Code make authenticated HTTP requests to external APIs. Supports 22 pre-built API connections with endpoint allowlisting, per-caller access control, and real-time event ingestion — all configured through a single JSON file.
 
@@ -29,7 +31,7 @@ The crypto layer uses **Ed25519** signatures for authentication and **X25519 ECD
 
 ### Local Mode (In-Process Library)
 
-In local mode, there is no separate server, no network port, and no encryption. Your application imports drawlatch's core functions directly and calls them in-process:
+In local mode, there is no separate server, no network port, and no encryption. Your application imports Drawlatch's core functions directly and calls them in-process:
 
 ```
 ┌──────────────────────────────────────────┐     Authenticated     ┌──────────────┐
@@ -678,7 +680,7 @@ These additional protections apply when running the two-component remote archite
 
 ### Local Mode Caveat
 
-When using drawlatch as an in-process library (local mode), secrets are resolved from `process.env` on the same machine as the agent. The encryption and mutual authentication layers are not used. The security value in local mode comes from **structured access control** (endpoint allowlisting, per-caller route isolation) rather than cryptographic secret isolation.
+When using Drawlatch as an in-process library (local mode), secrets are resolved from `process.env` on the same machine as the agent. The encryption and mutual authentication layers are not used. The security value in local mode comes from **structured access control** (endpoint allowlisting, per-caller route isolation) rather than cryptographic secret isolation.
 
 ## License
 

package/bin/drawlatch.js

@@ -0,0 +1,713 @@
+#!/usr/bin/env node
+
+// ── Drawlatch CLI ─────────────────────────────────────────────────
+// Entry point for the `drawlatch` command after global npm install.
+// Provides daemon management for the remote server, key generation,
+// log viewing, config introspection — all with zero extra dependencies.
+// ───────────────────────────────────────────────────────────────────
+
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  mkdirSync,
+  openSync,
+} from "node:fs";
+import { stat } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Paths & constants ─────────────────────────────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = resolve(__dirname, "..");
+const SERVER_ENTRY = join(PKG_ROOT, "dist/remote/server.js");
+const GENERATE_KEYS_ENTRY = join(PKG_ROOT, "dist/cli/generate-keys.js");
+
+// Import config helpers from compiled drawlatch code
+const { getConfigDir, getEnvFilePath, loadRemoteConfig } = await import(
+  join(PKG_ROOT, "dist/shared/config.js")
+);
+
+const CONFIG_DIR = getConfigDir();
+const ENV_FILE = getEnvFilePath();
+const PID_FILE = join(CONFIG_DIR, "drawlatch.pid");
+const LOG_DIR = join(CONFIG_DIR, "logs");
+const LOG_FILE = join(LOG_DIR, "drawlatch.log");
+
+// Read version from package.json
+const pkgJson = JSON.parse(
+  readFileSync(join(PKG_ROOT, "package.json"), "utf-8"),
+);
+const VERSION = pkgJson.version;
+
+// ── Argument parsing ──────────────────────────────────────────────
+const rawArgs = process.argv.slice(2);
+const subcommand =
+  rawArgs[0] && !rawArgs[0].startsWith("-") ? rawArgs.shift() : null;
+
+let values, positionals;
+try {
+  ({ values, positionals } = parseArgs({
+    args: rawArgs,
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+      foreground: { type: "boolean", short: "f", default: false },
+      tunnel: { type: "boolean", short: "t", default: false },
+      port: { type: "string" },
+      host: { type: "string" },
+      lines: { type: "string", short: "n", default: "50" },
+      follow: { type: "boolean", default: true },
+      path: { type: "boolean", default: false },
+    },
+    strict: false,
+    allowPositionals: true,
+  }));
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────
+if (values.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
+if (values.help && !subcommand) {
+  printHelp();
+  process.exit(0);
+}
+
+switch (subcommand) {
+  case null:
+    await cmdDefault();
+    break;
+  case "start":
+    if (values.help) {
+      printStartHelp();
+    } else {
+      await cmdStart();
+    }
+    break;
+  case "stop":
+    if (values.help) {
+      printStopHelp();
+    } else {
+      await cmdStop();
+    }
+    break;
+  case "restart":
+    if (values.help) {
+      printRestartHelp();
+    } else {
+      await cmdRestart();
+    }
+    break;
+  case "status":
+    if (values.help) {
+      printStatusHelp();
+    } else {
+      await cmdStatus();
+    }
+    break;
+  case "logs":
+    if (values.help) {
+      printLogsHelp();
+    } else {
+      await cmdLogs();
+    }
+    break;
+  case "config":
+    if (values.help) {
+      printConfigHelp();
+    } else {
+      cmdConfig();
+    }
+    break;
+  case "generate-keys":
+    if (values.help) {
+      printGenerateKeysHelp();
+    } else {
+      await cmdGenerateKeys();
+    }
+    break;
+  case "help":
+    printHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${subcommand}\n`);
+    printHelp();
+    process.exit(1);
+}
+
+// ── Commands ──────────────────────────────────────────────────────
+
+async function cmdDefault() {
+  const pid = readPid();
+  if (pid) {
+    await cmdStatus();
+  } else {
+    console.log("Drawlatch remote server is not running.\n");
+    printHelp();
+  }
+}
+
+async function cmdStart() {
+  if (values.foreground) return cmdStartForeground();
+
+  ensureConfigDir();
+
+  const existingPid = readPid();
+  if (existingPid) {
+    console.log(`Remote server is already running (PID ${existingPid}).`);
+    console.log(`  Use: drawlatch status`);
+    process.exit(0);
+  }
+
+  const config = loadRemoteConfig();
+  const port = values.port ? parseInt(values.port, 10) : config.port;
+  const host = values.host || config.host;
+
+  mkdirSync(LOG_DIR, { recursive: true });
+  const logFd = openSync(LOG_FILE, "a");
+
+  const child = spawn(process.execPath, [SERVER_ENTRY], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: {
+      ...process.env,
+      NODE_ENV: "production",
+      ...(values.port ? { DRAWLATCH_PORT: String(port) } : {}),
+      ...(values.host ? { DRAWLATCH_HOST: host } : {}),
+      ...(values.tunnel ? { DRAWLATCH_TUNNEL: "1" } : {}),
+    },
+    cwd: PKG_ROOT,
+  });
+
+  writeFileSync(PID_FILE, String(child.pid) + "\n");
+  child.unref();
+
+  console.log(`Starting drawlatch remote server on ${host}:${port}...`);
+  const healthy = await waitForHealth(host, port, 5000);
+
+  if (healthy) {
+    console.log(`\nRemote server is running (PID ${child.pid}).`);
+    console.log(`  Listening: ${host}:${port}`);
+    if (values.tunnel) {
+      // The tunnel starts asynchronously after the server is healthy —
+      // poll the health endpoint until the tunnel URL appears (up to 20s).
+      console.log(`  Tunnel:    waiting for cloudflared...`);
+      const tunnelUrl = await waitForTunnelUrl(host, port, 20000);
+      if (tunnelUrl) {
+        console.log(`  Tunnel:    ${tunnelUrl}`);
+        console.log(`  Webhooks:  ${tunnelUrl}/webhooks/<path>`);
+      } else {
+        console.log(`  Tunnel:    not available (check logs: drawlatch logs)`);
+      }
+    }
+    console.log(`  Logs:      drawlatch logs`);
+  } else {
+    console.log(
+      `\nServer started (PID ${child.pid}) but health check did not pass.`,
+    );
+    console.log(`  Check logs: drawlatch logs`);
+    await diagnoseStartFailure();
+  }
+}
+
+async function cmdStartForeground() {
+  process.env.NODE_ENV = process.env.NODE_ENV || "production";
+  if (values.port) process.env.DRAWLATCH_PORT = values.port;
+  if (values.host) process.env.DRAWLATCH_HOST = values.host;
+  if (values.tunnel) process.env.DRAWLATCH_TUNNEL = "1";
+
+  ensureConfigDir();
+
+  const { main } = await import(SERVER_ENTRY);
+  main();
+}
+
+async function cmdStop() {
+  const pid = readPid();
+  if (!pid) {
+    console.log("Remote server is not running.");
+    process.exit(0);
+  }
+
+  console.log(`Stopping remote server (PID ${pid})...`);
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // Process already gone
+    cleanPidFile();
+    console.log("Server stopped.");
+    return;
+  }
+
+  const stopped = await waitForExit(pid, 5000);
+  if (!stopped) {
+    console.log("Server did not stop gracefully, sending SIGKILL...");
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // Already gone
+    }
+  }
+
+  cleanPidFile();
+  console.log("Server stopped.");
+}
+
+async function cmdRestart() {
+  const pid = readPid();
+  if (pid) {
+    // If the previous server had an active tunnel, carry the flag forward
+    // so the restarted server also starts a tunnel (unless --tunnel is
+    // already set or the user explicitly omitted it).
+    if (!values.tunnel) {
+      const config = loadRemoteConfig();
+      const prevHealth = await healthCheckFull(config.host, config.port);
+      if (prevHealth?.tunnelUrl) {
+        console.log("Previous server had an active tunnel — re-enabling --tunnel.");
+        values.tunnel = true;
+      }
+    }
+    await cmdStop();
+  }
+  await cmdStart();
+}
+
+async function cmdStatus() {
+  const pid = readPid();
+  if (!pid) {
+    console.log("Drawlatch remote server is not running.");
+    process.exit(0);
+  }
+
+  const config = loadRemoteConfig();
+  const port = config.port;
+  const host = config.host;
+
+  let uptime = "unknown";
+  try {
+    const pidStat = await stat(PID_FILE);
+    uptime = formatUptime(Date.now() - pidStat.mtimeMs);
+  } catch {
+    // Can't stat PID file
+  }
+
+  const healthData = await healthCheckFull(host, port);
+
+  console.log("Drawlatch remote server is running.");
+  console.log(`  PID:             ${pid}`);
+  console.log(`  Listening:       ${host}:${port}`);
+  console.log(`  Uptime:          ${uptime}`);
+  console.log(
+    `  Health:          ${healthData ? "healthy" : "unhealthy (not responding)"}`,
+  );
+  if (healthData) {
+    console.log(`  Active sessions: ${healthData.activeSessions}`);
+    if (healthData.tunnelUrl) {
+      console.log(`  Tunnel:          ${healthData.tunnelUrl}`);
+    }
+  }
+}
+
+async function cmdLogs() {
+  if (!existsSync(LOG_FILE)) {
+    console.log("No log file found. Start the server first:");
+    console.log("  drawlatch start");
+    process.exit(0);
+  }
+
+  const lines = parseInt(values.lines, 10) || 50;
+  const follow = values.follow;
+
+  const tailArgs = follow
+    ? ["-n", String(lines), "-f", LOG_FILE]
+    : ["-n", String(lines), LOG_FILE];
+
+  const tail = spawn("tail", tailArgs, { stdio: "inherit" });
+
+  tail.on("error", () => {
+    // Fallback: read last N lines with Node.js if tail is not available
+    try {
+      const content = readFileSync(LOG_FILE, "utf-8");
+      const allLines = content.split("\n");
+      const lastLines = allLines.slice(-lines).join("\n");
+      console.log(lastLines);
+      if (follow) {
+        console.log(
+          "\n(Live following not available \u2014 'tail' command not found)",
+        );
+      }
+    } catch (err) {
+      console.error(`Error reading log file: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+  // Forward SIGINT to cleanly exit
+  process.on("SIGINT", () => {
+    tail.kill();
+    process.exit(0);
+  });
+
+  // Wait for tail to exit (when using --no-follow)
+  await new Promise((res) => tail.on("close", res));
+}
+
+function cmdConfig() {
+  ensureConfigDir();
+
+  if (values.path) {
+    console.log(join(CONFIG_DIR, "remote.config.json"));
+    return;
+  }
+
+  const config = loadRemoteConfig();
+
+  console.log(`\nDrawlatch Configuration`);
+  console.log(`=======================`);
+
+  console.log(`\nRemote Server:`);
+  console.log(`  Host:               ${config.host}`);
+  console.log(`  Port:               ${config.port}`);
+  console.log(`  Rate limit:         ${config.rateLimitPerMinute} req/min`);
+  console.log(`  Local keys dir:     ${config.localKeysDir}`);
+
+  const callerEntries = Object.entries(config.callers || {});
+  console.log(`  Callers:            ${callerEntries.length}`);
+  for (const [alias, caller] of callerEntries) {
+    console.log(
+      `    ${alias}: ${caller.connections ? caller.connections.length : 0} connection(s)`,
+    );
+  }
+
+  console.log(
+    `  Connectors:         ${config.connectors ? config.connectors.length : 0}`,
+  );
+
+  console.log(`\nPaths:`);
+  console.log(`  Config dir:  ${CONFIG_DIR}`);
+  console.log(`  Env file:    ${ENV_FILE}`);
+  console.log(`  Remote cfg:  ${join(CONFIG_DIR, "remote.config.json")}`);
+  console.log(`  Proxy cfg:   ${join(CONFIG_DIR, "proxy.config.json")}`);
+  console.log(`  Logs:        ${LOG_FILE}`);
+  console.log(`  PID file:    ${PID_FILE}`);
+  console.log();
+}
+
+async function cmdGenerateKeys() {
+  // Forward all remaining positional args to the generate-keys script
+  const child = spawn(process.execPath, [GENERATE_KEYS_ENTRY, ...positionals], {
+    stdio: "inherit",
+    cwd: PKG_ROOT,
+  });
+
+  await new Promise((res) => child.on("close", res));
+  process.exit(child.exitCode ?? 0);
+}
+
+// ── PID utilities ─────────────────────────────────────────────────
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM"; // EPERM = alive but owned by another user
+  }
+}
+
+function readPid() {
+  if (!existsSync(PID_FILE)) return null;
+  const raw = readFileSync(PID_FILE, "utf-8").trim();
+  const pid = parseInt(raw, 10);
+  if (isNaN(pid)) {
+    cleanPidFile();
+    return null;
+  }
+  if (!isProcessAlive(pid)) {
+    cleanPidFile();
+    return null;
+  }
+  return pid;
+}
+
+function cleanPidFile() {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // Already gone
+  }
+}
+
+// ── Health check utilities ────────────────────────────────────────
+
+async function healthCheck(host, port) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`http://${host}:${port}/health`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function healthCheckFull(host, port) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`http://${host}:${port}/health`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+async function waitForTunnelUrl(host, port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const data = await healthCheckFull(host, port);
+    if (data?.tunnelUrl) return data.tunnelUrl;
+    await sleep(500);
+  }
+  return null;
+}
+
+async function waitForHealth(host, port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await healthCheck(host, port)) return true;
+    await sleep(500);
+  }
+  return false;
+}
+
+async function waitForExit(pid, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (!isProcessAlive(pid)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+
+// ── Config utilities ──────────────────────────────────────────────
+
+function ensureConfigDir() {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+// ── Diagnostic utilities ──────────────────────────────────────────
+
+async function diagnoseStartFailure() {
+  if (!existsSync(LOG_FILE)) return;
+  try {
+    const content = readFileSync(LOG_FILE, "utf-8");
+    const lines = content.split("\n").slice(-20);
+    const eaddrinuse = lines.find((l) => l.includes("EADDRINUSE"));
+    const eacces = lines.find((l) => l.includes("EACCES"));
+    if (eaddrinuse) {
+      console.log("\n  Error: Port is already in use.");
+      console.log("  Another process may be using the same port.");
+    } else if (eacces) {
+      console.log("\n  Error: Permission denied.");
+      console.log("  Try using a port >= 1024.");
+    }
+  } catch {
+    // Best effort
+  }
+}
+
+// ── Output / formatting ──────────────────────────────────────────
+
+function formatUptime(ms) {
+  const s = Math.floor(ms / 1000);
+  const d = Math.floor(s / 86400);
+  const h = Math.floor((s % 86400) / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (d > 0) return `${d}d ${h}h ${m}m`;
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ── Help text ─────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+drawlatch v${VERSION}
+
+Usage: drawlatch [command] [options]
+
+Commands:
+  start              Start the remote server (background by default)
+  stop               Stop the background remote server
+  restart            Restart the background remote server
+  status             Show server status (PID, port, uptime, health, sessions)
+  logs               View and follow remote server logs
+  config             Show effective configuration
+  generate-keys      Generate Ed25519 + X25519 keypairs
+
+Options:
+  -h, --help         Show this help message
+  -v, --version      Show version number
+
+Running 'drawlatch' with no arguments shows status (if running) or this help.
+
+Examples:
+  drawlatch                            Show status or help
+  drawlatch start                      Start remote server in background
+  drawlatch start -f                   Start remote server in foreground
+  drawlatch start -f --tunnel          Start with a public tunnel for webhooks
+  drawlatch start --port 8080          Start on a custom port
+  drawlatch status                     Check if server is running
+  drawlatch logs -n 100                View last 100 log lines
+  drawlatch generate-keys remote       Generate remote server keypair
+  drawlatch generate-keys local mybot  Generate local keypair for alias "mybot"
+`);
+}
+
+function printStartHelp() {
+  console.log(`
+drawlatch start
+
+Start the drawlatch remote server.
+
+Usage: drawlatch start [options]
+
+Options:
+  -f, --foreground   Run in foreground (default when no command given)
+  -t, --tunnel       Start a Cloudflare tunnel for webhook ingestion (requires cloudflared)
+  --port <number>    Override the configured port
+  --host <address>   Override the configured host
+  -h, --help         Show this help message
+
+By default, starts the server as a background daemon. The server
+process ID is stored in ~/.drawlatch/drawlatch.pid.
+`);
+}
+
+function printStopHelp() {
+  console.log(`
+drawlatch stop
+
+Stop the drawlatch remote server.
+
+Usage: drawlatch stop [options]
+
+Options:
+  -h, --help   Show this help message
+
+Sends SIGTERM to the server process and waits for graceful shutdown.
+Falls back to SIGKILL if the process does not exit within 5 seconds.
+`);
+}
+
+function printRestartHelp() {
+  console.log(`
+drawlatch restart
+
+Restart the drawlatch remote server.
+
+Usage: drawlatch restart [options]
+
+Options:
+  --port <number>    Override the configured port
+  --host <address>   Override the configured host
+  -h, --help         Show this help message
+
+Stops the running server (if any) and starts a new instance.
+`);
+}
+
+function printStatusHelp() {
+  console.log(`
+drawlatch status
+
+Show server status.
+
+Usage: drawlatch status [options]
+
+Options:
+  -h, --help   Show this help message
+
+Displays PID, host, port, uptime, health check result, and
+active session count.
+`);
+}
+
+function printLogsHelp() {
+  console.log(`
+drawlatch logs
+
+View server logs.
+
+Usage: drawlatch logs [options]
+
+Options:
+  -n, --lines <number>  Number of lines to show (default: 50)
+  --no-follow            Print lines and exit (default: follow/tail)
+  -h, --help             Show this help message
+
+Log file: ~/.drawlatch/logs/drawlatch.log
+`);
+}
+
+function printConfigHelp() {
+  console.log(`
+drawlatch config
+
+Show effective configuration.
+
+Usage: drawlatch config [options]
+
+Options:
+  --path       Print the config file path only
+  -h, --help   Show this help message
+
+Reads ~/.drawlatch/remote.config.json and displays the effective
+server configuration including callers and connections.
+`);
+}
+
+function printGenerateKeysHelp() {
+  console.log(`
+drawlatch generate-keys
+
+Generate Ed25519 + X25519 keypairs for authentication and encryption.
+
+Usage: drawlatch generate-keys <subcommand> [options]
+
+Subcommands:
+  local [alias]      Generate MCP proxy (local) keypair
+                     Alias defaults to "default" if omitted.
+                     Keys are stored in keys/local/<alias>/
+  remote             Generate remote server keypair
+  --dir <path>       Generate keypair in a custom directory
+  show <path>        Show fingerprint of an existing keypair
+
+Keys are saved as PEM files:
+  <dir>/signing.pub.pem       Ed25519 public key (safe to share)
+  <dir>/signing.key.pem       Ed25519 private key (keep secret!)
+  <dir>/exchange.pub.pem      X25519 public key (safe to share)
+  <dir>/exchange.key.pem      X25519 private key (keep secret!)
+`);
+}

package/dist/remote/server.d.ts

@@ -12,7 +12,6 @@
  *   - Maintains an audit log of all operations
  *   - Rate-limits requests per session
  */
-import 'dotenv/config';
 import { type RemoteServerConfig, type ResolvedRoute } from '../shared/config.js';
 import { EncryptedChannel, type PublicKeyBundle } from '../shared/crypto/index.js';
 import { HandshakeResponder, type HandshakeInit } from '../shared/protocol/index.js';
@@ -100,4 +99,5 @@ export interface CreateAppOptions {
     ingestorManager?: IngestorManager;
 }
 export declare function createApp(options?: CreateAppOptions): import("express-serve-static-core").Express;
+export declare function main(): void;
 //# sourceMappingURL=server.d.ts.map

package/dist/remote/server.js

@@ -12,13 +12,29 @@
  *   - Maintains an audit log of all operations
  *   - Rate-limits requests per session
  */
-import 'dotenv/config';
+import dotenv from 'dotenv';
 import express from 'express';
 import fs from 'node:fs';
-import { loadRemoteConfig, resolveRoutes, resolveCallerRoutes, resolveSecrets, resolvePlaceholders, } from '../shared/config.js';
+import { loadRemoteConfig, resolveRoutes, resolveCallerRoutes, resolveSecrets, resolvePlaceholders, getEnvFilePath, } from '../shared/config.js';
 import { loadKeyBundle, loadPublicKeys, EncryptedChannel, } from '../shared/crypto/index.js';
 import { HandshakeResponder, } from '../shared/protocol/index.js';
 import { IngestorManager } from './ingestors/index.js';
+// ── Environment loading ─────────────────────────────────────────────────────
+/** Load environment from ~/.drawlatch/.env, falling back to cwd .env (legacy). */
+function loadEnvFile() {
+    const configDirEnvPath = getEnvFilePath();
+    if (fs.existsSync(configDirEnvPath)) {
+        dotenv.config({ path: configDirEnvPath });
+        return;
+    }
+    // Backward compat: fall back to cwd .env
+    const result = dotenv.config();
+    if (result.parsed) {
+        console.warn(`[remote] Loaded .env from working directory. ` +
+            `Move it to ${configDirEnvPath} for portable operation.`);
+    }
+}
+loadEnvFile();
 // ── State ──────────────────────────────────────────────────────────────────
 const sessions = new Map();
 const pendingHandshakes = new Map();
@@ -446,9 +462,24 @@ export function createApp(options = {}) {
             status: 'ok',
             activeSessions: sessions.size,
             uptime: process.uptime(),
+            tunnelUrl: process.env.DRAWLATCH_TUNNEL_URL ?? null,
         });
     });
     // ── Webhook receiver ─────────────────────────────────────────────────
+    // Trello (and potentially other services) send a HEAD request to the
+    // callback URL to verify it is reachable before activating the webhook.
+    // Respond with 200 if at least one ingestor is registered for the path.
+    app.head('/webhooks/:path', (req, res) => {
+        const webhookPath = req.params.path;
+        const mgr = app.locals.ingestorManager;
+        const ingestors = mgr.getWebhookIngestors(webhookPath);
+        if (ingestors.length === 0) {
+            res.status(404).end();
+        }
+        else {
+            res.status(200).end();
+        }
+    });
     app.post('/webhooks/:path', (req, res) => {
         const webhookPath = req.params.path;
         const mgr = app.locals.ingestorManager;
@@ -482,29 +513,80 @@ export function createApp(options = {}) {
     return app;
 }
 // ── Start ──────────────────────────────────────────────────────────────────
-function main() {
+export function main() {
     const config = loadRemoteConfig();
+    const port = process.env.DRAWLATCH_PORT ? parseInt(process.env.DRAWLATCH_PORT, 10) : config.port;
+    const host = process.env.DRAWLATCH_HOST ?? config.host;
+    const useTunnel = process.env.DRAWLATCH_TUNNEL === '1';
     const app = createApp();
     const ingestorManager = app.locals.ingestorManager;
-    const server = app.listen(config.port, config.host, () => {
-        console.log(`[remote] Secure remote server listening on ${config.host}:${config.port}`);
-        // Start ingestors after the server is listening
+    // Holds the tunnel stop function if a tunnel is active (set inside the
+    // listen callback, read by the shutdown handler — both share this scope).
+    let stopTunnel;
+    const server = app.listen(port, host, () => void (async () => {
+        console.log(`[remote] Secure remote server listening on ${host}:${port}`);
+        // If a tunnel was requested, start it before ingestors so that
+        // process.env.DRAWLATCH_TUNNEL_URL is available during secret resolution.
+        if (useTunnel) {
+            try {
+                const { startTunnel } = await import('./tunnel.js');
+                const tunnel = await startTunnel({ port, host });
+                stopTunnel = tunnel.stop;
+                process.env.DRAWLATCH_TUNNEL_URL = tunnel.url;
+                // Auto-populate callback URL env vars for webhook ingestors whose
+                // connection templates reference an env var that is not yet set.
+                for (const [callerAlias, _callerConfig] of Object.entries(config.callers)) {
+                    const rawRoutes = resolveCallerRoutes(config, callerAlias);
+                    for (const route of rawRoutes) {
+                        const callbackTpl = route.ingestor?.webhook?.callbackUrl;
+                        const webhookPath = route.ingestor?.webhook?.path;
+                        if (!callbackTpl || !webhookPath)
+                            continue;
+                        // Extract env var name from "${VAR}" pattern
+                        const match = /^\$\{(\w+)\}$/.exec(callbackTpl);
+                        if (match) {
+                            const envVar = match[1];
+                            if (!process.env[envVar]) {
+                                const fullUrl = `${tunnel.url}/webhooks/${webhookPath}`;
+                                process.env[envVar] = fullUrl;
+                                console.log(`[remote] Auto-set ${envVar}=${fullUrl}`);
+                            }
+                        }
+                    }
+                }
+                console.log(`[remote] Tunnel active: ${tunnel.url}`);
+                console.log(`[remote] Webhook URL:   ${tunnel.url}/webhooks/<path>`);
+            }
+            catch (err) {
+                console.error('[remote] Failed to start tunnel:', err);
+                console.error('[remote] Continuing without tunnel. Webhooks will only work on localhost.');
+            }
+        }
+        // Start ingestors after tunnel (if any) is ready
         ingestorManager.startAll().catch((err) => {
             console.error('[remote] Failed to start ingestors:', err);
         });
-    });
-    // Graceful shutdown: stop ingestors, then close the server.
+    })());
+    // Graceful shutdown: stop tunnel, then ingestors, then close the server.
     const shutdown = () => {
         console.log('[remote] Shutting down gracefully...');
-        ingestorManager
-            .stopAll()
-            .catch((err) => {
-            console.error('[remote] Error stopping ingestors:', err);
-        })
-            .finally(() => {
-            server.close(() => {
-                console.log('[remote] Server closed.');
-                process.exit(0);
+        // Stop tunnel first (fast — just kills a child process)
+        const tunnelDone = stopTunnel
+            ? stopTunnel().catch((err) => {
+                console.error('[remote] Error stopping tunnel:', err);
+            })
+            : Promise.resolve();
+        void tunnelDone.then(() => {
+            ingestorManager
+                .stopAll()
+                .catch((err) => {
+                console.error('[remote] Error stopping ingestors:', err);
+            })
+                .finally(() => {
+                server.close(() => {
+                    console.log('[remote] Server closed.');
+                    process.exit(0);
+                });
             });
         });
         // Force exit after 10 seconds if connections don't drain
@@ -518,12 +600,8 @@ function main() {
 }
 // Only run when executed directly (not when imported as a library).
 // Check if the entry script is this file (covers both ts-node and compiled js).
-// Also check PM2's pm_exec_path for cluster mode where argv[1] is PM2's internal module.
 const entryScript = process.argv[1] ?? '';
-const pm2ExecPath = process.env.pm_exec_path ?? '';
-const isDirectRun = entryScript.endsWith('remote/server.ts') ||
-    entryScript.endsWith('remote/server.js') ||
-    pm2ExecPath.endsWith('remote/server.js');
+const isDirectRun = entryScript.endsWith('remote/server.ts') || entryScript.endsWith('remote/server.js');
 if (isDirectRun) {
     try {
         main();

package/dist/remote/tunnel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tunnel management for exposing the local Drawlatch server to the internet.
+ *
+ * Spawns a `cloudflared tunnel` process that creates a free Cloudflare Quick
+ * Tunnel, parses the assigned public URL from its stderr output, and provides
+ * graceful start/stop lifecycle management.
+ *
+ * The tunnel URL is injected into `process.env.DRAWLATCH_TUNNEL_URL` so that
+ * webhook ingestors can reference it during secret resolution (e.g., setting
+ * TRELLO_CALLBACK_URL=${DRAWLATCH_TUNNEL_URL}/webhooks/trello in .env).
+ */
+export interface TunnelOptions {
+    /** Local port the server is listening on. */
+    port: number;
+    /** Local host the server is bound to. */
+    host: string;
+    /** Timeout (ms) to wait for the tunnel URL to be assigned. Default: 15 000. */
+    timeout?: number;
+}
+export interface TunnelResult {
+    /** The public HTTPS URL assigned by Cloudflare (e.g. https://abc.trycloudflare.com). */
+    url: string;
+    /** Gracefully stop the tunnel process. */
+    stop: () => Promise<void>;
+}
+/**
+ * Check whether the `cloudflared` binary is available on the system PATH.
+ * Resolves to `true` if available, `false` otherwise.
+ */
+export declare function isCloudflaredAvailable(): Promise<boolean>;
+/**
+ * Start a Cloudflare Quick Tunnel that forwards traffic from a public
+ * `*.trycloudflare.com` URL to the local Drawlatch server.
+ *
+ * Resolves once the tunnel URL has been parsed from cloudflared's output.
+ * Rejects if `cloudflared` is not installed, fails to start, or does not
+ * emit a URL within the configured timeout.
+ */
+export declare function startTunnel(options: TunnelOptions): Promise<TunnelResult>;
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/remote/tunnel.js

@@ -0,0 +1,116 @@
+/**
+ * Tunnel management for exposing the local Drawlatch server to the internet.
+ *
+ * Spawns a `cloudflared tunnel` process that creates a free Cloudflare Quick
+ * Tunnel, parses the assigned public URL from its stderr output, and provides
+ * graceful start/stop lifecycle management.
+ *
+ * The tunnel URL is injected into `process.env.DRAWLATCH_TUNNEL_URL` so that
+ * webhook ingestors can reference it during secret resolution (e.g., setting
+ * TRELLO_CALLBACK_URL=${DRAWLATCH_TUNNEL_URL}/webhooks/trello in .env).
+ */
+import { spawn } from 'node:child_process';
+import { createLogger } from '../shared/logger.js';
+const log = createLogger('tunnel');
+// ── Helpers ──────────────────────────────────────────────────────────────
+/** Regex to extract the Cloudflare Quick Tunnel URL from cloudflared output. */
+const TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+const INSTALL_HINT = 'Install it: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+/**
+ * Check whether the `cloudflared` binary is available on the system PATH.
+ * Resolves to `true` if available, `false` otherwise.
+ */
+export async function isCloudflaredAvailable() {
+    return new Promise((resolve) => {
+        const child = spawn('cloudflared', ['--version'], { stdio: 'ignore' });
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
+    });
+}
+// ── Main entry point ─────────────────────────────────────────────────────
+/**
+ * Start a Cloudflare Quick Tunnel that forwards traffic from a public
+ * `*.trycloudflare.com` URL to the local Drawlatch server.
+ *
+ * Resolves once the tunnel URL has been parsed from cloudflared's output.
+ * Rejects if `cloudflared` is not installed, fails to start, or does not
+ * emit a URL within the configured timeout.
+ */
+export async function startTunnel(options) {
+    const { port, host, timeout = 15_000 } = options;
+    // ── Pre-flight check ────────────────────────────────────────────────
+    const available = await isCloudflaredAvailable();
+    if (!available) {
+        throw new Error(`cloudflared binary not found. ${INSTALL_HINT}`);
+    }
+    // ── Spawn cloudflared ───────────────────────────────────────────────
+    const localUrl = `http://${host}:${port}`;
+    log.info(`Starting Cloudflare Quick Tunnel → ${localUrl}`);
+    const child = spawn('cloudflared', ['tunnel', '--url', localUrl, '--no-autoupdate'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let tunnelUrl = null;
+        // ── Timeout guard ───────────────────────────────────────────────
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill('SIGTERM');
+                reject(new Error(`Timed out after ${timeout}ms waiting for tunnel URL`));
+            }
+        }, timeout);
+        // ── Parse URL from stderr (cloudflared logs to stderr) ──────────
+        const handleData = (chunk) => {
+            const line = chunk.toString('utf-8');
+            log.debug(line.trimEnd());
+            if (settled)
+                return;
+            const match = TUNNEL_URL_RE.exec(line);
+            if (match) {
+                tunnelUrl = match[0];
+                settled = true;
+                clearTimeout(timer);
+                log.info(`Tunnel URL: ${tunnelUrl}`);
+                resolve({ url: tunnelUrl, stop: stopTunnel });
+            }
+        };
+        child.stderr?.on('data', handleData);
+        child.stdout?.on('data', handleData);
+        // ── Handle unexpected exit before URL is found ──────────────────
+        child.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`cloudflared failed to start: ${err.message}`));
+            }
+        });
+        child.on('close', (code) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`cloudflared exited with code ${code} before emitting a URL`));
+            }
+            else if (tunnelUrl) {
+                // Tunnel was active but has now dropped
+                log.warn('cloudflared process exited unexpectedly — tunnel is down');
+            }
+        });
+        // ── Stop helper ─────────────────────────────────────────────────
+        async function stopTunnel() {
+            if (child.exitCode !== null)
+                return; // already exited
+            return new Promise((res) => {
+                const killTimer = setTimeout(() => {
+                    log.warn('cloudflared did not exit in time, sending SIGKILL');
+                    child.kill('SIGKILL');
+                }, 5_000);
+                child.on('close', () => {
+                    clearTimeout(killTimer);
+                    log.info('Tunnel stopped');
+                    res();
+                });
+                child.kill('SIGTERM');
+            });
+        }
+    });
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/shared/config.d.ts

@@ -26,6 +26,7 @@ export declare function getKeysDir(): string;
 export declare function getLocalKeysDir(): string;
 export declare function getRemoteKeysDir(): string;
 export declare function getPeerKeysDir(): string;
+export declare function getEnvFilePath(): string;
 /** MCP proxy (local) configuration */
 export interface ProxyConfig {
     /** Remote server URL */

package/dist/shared/config.js

@@ -45,6 +45,9 @@ export function getRemoteKeysDir() {
 export function getPeerKeysDir() {
     return path.join(getKeysDir(), 'peers');
 }
+export function getEnvFilePath() {
+    return path.join(getConfigDir(), '.env');
+}
 // ── Defaults ─────────────────────────────────────────────────────────────────
 function proxyDefaults() {
     return {

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@wolpertingerlabs/drawlatch",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Encrypted MCP proxy with mutual authentication. Local MCP server forwards requests through an encrypted channel to a remote secrets-holding server.",
   "type": "module",
   "main": "./dist/mcp/server.js",
   "types": "./dist/mcp/server.d.ts",
+  "bin": {
+    "drawlatch": "./bin/drawlatch.js"
+  },
   "files": [
     "dist",
     "!dist/**/*.test.*",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
+    "bin",
     "README.md",
     "CONNECTIONS.md",
     "INGESTORS.md"
@@ -52,7 +56,6 @@
     "generate-keys": "tsx src/cli/generate-keys.ts",
     "start:remote": "NODE_ENV=production node dist/remote/server.js",
     "start:mcp": "node dist/mcp/server.js",
-    "redeploy:prod": "node start-server.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -61,7 +64,8 @@
     "format": "prettier --write 'src/**/*.ts' '*.{json,ts,js}'",
     "format:check": "prettier --check 'src/**/*.ts' '*.{json,ts,js}'",
     "prepublishOnly": "npm run lint && npm test && npm run build",
-    "publish:dry-run": "npm publish --dry-run"
+    "publish:dry-run": "npm publish --dry-run",
+    "reload": "npm install --include=dev && npm run build && VERSION=$(node -p \"require('./package.json').version\") && npm pack --pack-destination /tmp && npm install -g \"/tmp/wolpertingerlabs-drawlatch-$VERSION.tgz\" && rm \"/tmp/wolpertingerlabs-drawlatch-$VERSION.tgz\""
   },
   "engines": {
     "node": ">=22"