@wolpertingerlabs/drawlatch 1.0.0-alpha.2 → 1.0.0-alpha.4

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

@@ -57,10 +57,11 @@ try {
       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 },
+      follow: { type: "boolean", default: false },
       path: { type: "boolean", default: false },
     },
     strict: false,
@@ -182,6 +183,7 @@ async function cmdStart() {
       NODE_ENV: "production",
       ...(values.port ? { DRAWLATCH_PORT: String(port) } : {}),
       ...(values.host ? { DRAWLATCH_HOST: host } : {}),
+      ...(values.tunnel ? { DRAWLATCH_TUNNEL: "1" } : {}),
     },
     cwd: PKG_ROOT,
   });
@@ -195,6 +197,18 @@ async function cmdStart() {
   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(
@@ -209,6 +223,7 @@ 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();
 
@@ -250,6 +265,17 @@ async function cmdStop() {
 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();
@@ -285,6 +311,9 @@ async function cmdStatus() {
   );
   if (healthData) {
     console.log(`  Active sessions: ${healthData.activeSessions}`);
+    if (healthData.tunnelUrl) {
+      console.log(`  Tunnel:          ${healthData.tunnelUrl}`);
+    }
   }
 }
 
@@ -449,6 +478,16 @@ async function healthCheckFull(host, port) {
   }
 }
 
+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) {
@@ -537,6 +576,7 @@ 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
@@ -555,6 +595,7 @@ 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
@@ -623,7 +664,7 @@ Usage: drawlatch logs [options]
 
 Options:
   -n, --lines <number>  Number of lines to show (default: 50)
-  --no-follow            Print lines and exit (default: follow/tail)
+  --follow               Follow/tail the log output (default: print and exit)
   -h, --help             Show this help message
 
 Log file: ~/.drawlatch/logs/drawlatch.log

package/dist/connections/anthropic.json

@@ -12,5 +12,21 @@
   },
   "allowedEndpoints": [
     "https://api.anthropic.com/**"
-  ]
+  ],
+  "testConnection": {
+    "method": "POST",
+    "url": "https://api.anthropic.com/v1/messages",
+    "body": {
+      "model": "claude-3-haiku-20240307",
+      "max_tokens": 1,
+      "messages": [
+        {
+          "role": "user",
+          "content": "hi"
+        }
+      ]
+    },
+    "description": "Sends a minimal message to verify API key",
+    "expectedStatus": [200]
+  }
 }

package/dist/connections/bluesky.json

@@ -22,5 +22,44 @@
       "deduplicateBy": "uri",
       "eventType": "notification"
     }
+  },
+  "testIngestor": {
+    "description": "Fetches notifications to verify Bluesky access token",
+    "strategy": "poll_once",
+    "request": {
+      "url": "https://bsky.social/xrpc/app.bsky.notification.listNotifications?limit=1",
+      "expectedStatus": [200]
+    }
+  },
+  "listenerConfig": {
+    "name": "Bluesky Poll Listener",
+    "description": "Polls Bluesky notifications at a configurable interval.",
+    "fields": [
+      {
+        "key": "intervalMs",
+        "label": "Poll Interval (ms)",
+        "description": "How often to check for new notifications, in milliseconds.",
+        "type": "number",
+        "default": 60000,
+        "min": 10000,
+        "max": 3600000,
+        "group": "Connection"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://bsky.social/xrpc/app.bsky.actor.getProfile?actor=did:self",
+    "description": "Fetches the authenticated user's profile",
+    "expectedStatus": [200, 400]
   }
 }

package/dist/connections/devin.json

@@ -11,5 +11,9 @@
   },
   "allowedEndpoints": [
     "https://api.devin.ai/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://api.devin.ai/v1/sessions",
+    "description": "Lists Devin sessions to verify API key"
+  }
 }

package/dist/connections/discord-bot.json

@@ -20,5 +20,93 @@
       "protocol": "discord",
       "intents": 3276799
     }
+  },
+  "testIngestor": {
+    "description": "Verifies the bot token has Gateway access",
+    "strategy": "websocket_auth",
+    "request": {
+      "url": "https://discord.com/api/v10/gateway/bot",
+      "description": "Checks bot token has gateway access"
+    }
+  },
+  "listenerConfig": {
+    "name": "Discord Gateway Listener",
+    "description": "Real-time events from Discord via the Gateway WebSocket.",
+    "fields": [
+      {
+        "key": "eventFilter",
+        "label": "Event Types",
+        "description": "Which Gateway event types to capture. Leave empty for all.",
+        "type": "multiselect",
+        "default": [],
+        "options": [
+          {"value": "MESSAGE_CREATE", "label": "Message Create"},
+          {"value": "MESSAGE_UPDATE", "label": "Message Update"},
+          {"value": "MESSAGE_DELETE", "label": "Message Delete"},
+          {"value": "MESSAGE_REACTION_ADD", "label": "Reaction Add"},
+          {"value": "MESSAGE_REACTION_REMOVE", "label": "Reaction Remove"},
+          {"value": "GUILD_MEMBER_ADD", "label": "Member Join"},
+          {"value": "GUILD_MEMBER_REMOVE", "label": "Member Leave"},
+          {"value": "CHANNEL_CREATE", "label": "Channel Create"},
+          {"value": "CHANNEL_UPDATE", "label": "Channel Update"},
+          {"value": "CHANNEL_DELETE", "label": "Channel Delete"},
+          {"value": "PRESENCE_UPDATE", "label": "Presence Update"},
+          {"value": "TYPING_START", "label": "Typing Start"},
+          {"value": "VOICE_STATE_UPDATE", "label": "Voice State Update"}
+        ],
+        "group": "Filtering"
+      },
+      {
+        "key": "guildIds",
+        "label": "Server (Guild) IDs",
+        "description": "Only receive events from these Discord servers. Leave empty for all.",
+        "type": "text[]",
+        "placeholder": "e.g., 123456789012345678",
+        "dynamicOptions": {
+          "url": "https://discord.com/api/v10/users/@me/guilds",
+          "labelField": "name",
+          "valueField": "id"
+        },
+        "group": "Filtering"
+      },
+      {
+        "key": "channelIds",
+        "label": "Channel IDs",
+        "description": "Only receive events from these channels. Leave empty for all.",
+        "type": "text[]",
+        "placeholder": "e.g., 123456789012345678",
+        "group": "Filtering"
+      },
+      {
+        "key": "userIds",
+        "label": "User IDs",
+        "description": "Only receive events from these users. Leave empty for all.",
+        "type": "text[]",
+        "placeholder": "e.g., 123456789012345678",
+        "group": "Filtering"
+      },
+      {
+        "key": "intents",
+        "label": "Gateway Intents",
+        "description": "Bitmask controlling which events the bot receives. See Discord docs for values.",
+        "type": "number",
+        "default": 3276799,
+        "group": "Advanced"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://discord.com/api/v10/users/@me",
+    "description": "Fetches the authenticated bot user"
   }
 }

package/dist/connections/discord-oauth.json

@@ -12,5 +12,9 @@
   },
   "allowedEndpoints": [
     "https://discord.com/api/v10/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://discord.com/api/v10/users/@me",
+    "description": "Fetches the authenticated OAuth2 user"
+  }
 }

package/dist/connections/github.json

@@ -21,5 +21,62 @@
       "signatureHeader": "X-Hub-Signature-256",
       "signatureSecret": "GITHUB_WEBHOOK_SECRET"
     }
+  },
+  "testIngestor": {
+    "description": "Verifies that the GitHub webhook secret is configured",
+    "strategy": "webhook_verify",
+    "requireSecrets": ["GITHUB_WEBHOOK_SECRET"]
+  },
+  "listenerConfig": {
+    "name": "GitHub Webhook Listener",
+    "description": "Receives real-time events from GitHub via webhooks. Supports multiple concurrent instances to filter events from different repositories.",
+    "supportsMultiInstance": true,
+    "fields": [
+      {
+        "key": "repoFilter",
+        "label": "Repository Filter",
+        "description": "Only capture webhook events from these repositories (owner/repo format). Leave empty for all.",
+        "type": "text[]",
+        "instanceKey": true,
+        "placeholder": "e.g., octocat/Hello-World",
+        "group": "Filtering"
+      },
+      {
+        "key": "eventFilter",
+        "label": "Event Types",
+        "description": "Which GitHub event types to capture. Leave empty for all.",
+        "type": "multiselect",
+        "default": [],
+        "options": [
+          {"value": "push", "label": "Push"},
+          {"value": "pull_request", "label": "Pull Request"},
+          {"value": "issues", "label": "Issues"},
+          {"value": "issue_comment", "label": "Issue Comment"},
+          {"value": "create", "label": "Branch/Tag Created"},
+          {"value": "delete", "label": "Branch/Tag Deleted"},
+          {"value": "release", "label": "Release"},
+          {"value": "workflow_run", "label": "Workflow Run"},
+          {"value": "check_run", "label": "Check Run"},
+          {"value": "star", "label": "Star"},
+          {"value": "fork", "label": "Fork"},
+          {"value": "deployment", "label": "Deployment"}
+        ],
+        "group": "Filtering"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://api.github.com/user",
+    "description": "Fetches the authenticated user profile"
   }
 }

package/dist/connections/google-ai.json

@@ -11,5 +11,9 @@
   },
   "allowedEndpoints": [
     "https://generativelanguage.googleapis.com/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://generativelanguage.googleapis.com/v1beta/models",
+    "description": "Lists available Gemini models"
+  }
 }

package/dist/connections/google.json

@@ -24,5 +24,9 @@
     "https://youtube.googleapis.com/**",
     "https://youtubeanalytics.googleapis.com/**",
     "https://cloudresourcemanager.googleapis.com/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://www.googleapis.com/oauth2/v1/userinfo",
+    "description": "Fetches the authenticated user info"
+  }
 }

package/dist/connections/hex.json

@@ -10,5 +10,9 @@
   },
   "allowedEndpoints": [
     "https://app.hex.tech/api/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://app.hex.tech/api/v1/user/me",
+    "description": "Fetches the authenticated Hex user"
+  }
 }

package/dist/connections/lichess.json

@@ -11,5 +11,9 @@
   "allowedEndpoints": [
     "https://explorer.lichess.ovh/**",
     "https://lichess.org/api/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://lichess.org/api/account",
+    "description": "Fetches the authenticated Lichess account"
+  }
 }

package/dist/connections/linear.json

@@ -25,5 +25,49 @@
       "deduplicateBy": "id",
       "eventType": "issue_updated"
     }
+  },
+  "testIngestor": {
+    "description": "Executes a minimal GraphQL query to verify Linear API access",
+    "strategy": "poll_once",
+    "request": {
+      "method": "POST",
+      "url": "https://api.linear.app/graphql",
+      "body": {"query": "{ viewer { id } }"},
+      "expectedStatus": [200]
+    }
+  },
+  "listenerConfig": {
+    "name": "Linear Poll Listener",
+    "description": "Polls Linear for recently updated issues at a configurable interval.",
+    "fields": [
+      {
+        "key": "intervalMs",
+        "label": "Poll Interval (ms)",
+        "description": "How often to check for new events, in milliseconds.",
+        "type": "number",
+        "default": 60000,
+        "min": 10000,
+        "max": 3600000,
+        "group": "Connection"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "method": "POST",
+    "url": "https://api.linear.app/graphql",
+    "body": {
+      "query": "{ viewer { id name } }"
+    },
+    "description": "Fetches the authenticated user via GraphQL"
   }
 }

package/dist/connections/mastodon.json

@@ -21,5 +21,43 @@
       "deduplicateBy": "id",
       "eventType": "status"
     }
+  },
+  "testIngestor": {
+    "description": "Verifies Mastodon credentials by checking account",
+    "strategy": "poll_once",
+    "request": {
+      "url": "https://mastodon.social/api/v1/accounts/verify_credentials",
+      "expectedStatus": [200]
+    }
+  },
+  "listenerConfig": {
+    "name": "Mastodon Poll Listener",
+    "description": "Polls the Mastodon home timeline at a configurable interval.",
+    "fields": [
+      {
+        "key": "intervalMs",
+        "label": "Poll Interval (ms)",
+        "description": "How often to check for new statuses, in milliseconds.",
+        "type": "number",
+        "default": 60000,
+        "min": 10000,
+        "max": 3600000,
+        "group": "Connection"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://mastodon.social/api/v1/accounts/verify_credentials",
+    "description": "Verifies Mastodon account credentials"
   }
 }

package/dist/connections/notion.json

@@ -29,5 +29,45 @@
       "deduplicateBy": "id",
       "eventType": "page_updated"
     }
+  },
+  "testIngestor": {
+    "description": "Executes a single search poll to verify Notion API access",
+    "strategy": "poll_once",
+    "request": {
+      "method": "POST",
+      "url": "https://api.notion.com/v1/search",
+      "body": {"page_size": 1},
+      "expectedStatus": [200]
+    }
+  },
+  "listenerConfig": {
+    "name": "Notion Poll Listener",
+    "description": "Polls Notion for recently edited pages at a configurable interval.",
+    "fields": [
+      {
+        "key": "intervalMs",
+        "label": "Poll Interval (ms)",
+        "description": "How often to check for new events, in milliseconds.",
+        "type": "number",
+        "default": 60000,
+        "min": 10000,
+        "max": 3600000,
+        "group": "Connection"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://api.notion.com/v1/users/me",
+    "description": "Fetches the authenticated bot user"
   }
 }

package/dist/connections/openai.json

@@ -12,5 +12,9 @@
   },
   "allowedEndpoints": [
     "https://api.openai.com/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://api.openai.com/v1/models",
+    "description": "Lists available models"
+  }
 }

package/dist/connections/openrouter.json

@@ -12,5 +12,9 @@
   },
   "allowedEndpoints": [
     "https://openrouter.ai/api/**"
-  ]
+  ],
+  "testConnection": {
+    "url": "https://openrouter.ai/api/v1/models",
+    "description": "Lists available models"
+  }
 }

package/dist/connections/reddit.json

@@ -24,5 +24,55 @@
       "deduplicateBy": "data.name",
       "eventType": "new_post"
     }
+  },
+  "testIngestor": {
+    "description": "Fetches the authenticated user to verify Reddit API access",
+    "strategy": "poll_once",
+    "request": {
+      "url": "https://oauth.reddit.com/api/v1/me",
+      "expectedStatus": [200]
+    }
+  },
+  "listenerConfig": {
+    "name": "Reddit Poll Listener",
+    "description": "Polls a subreddit for new posts at a configurable interval. Supports multiple concurrent instances to watch different subreddits simultaneously.",
+    "supportsMultiInstance": true,
+    "fields": [
+      {
+        "key": "subreddit",
+        "label": "Subreddit",
+        "description": "The subreddit to watch for new posts (without the r/ prefix).",
+        "type": "text",
+        "required": true,
+        "instanceKey": true,
+        "overrideKey": "REDDIT_SUBREDDIT",
+        "placeholder": "e.g., rust",
+        "group": "Connection"
+      },
+      {
+        "key": "intervalMs",
+        "label": "Poll Interval (ms)",
+        "description": "How often to check for new posts, in milliseconds.",
+        "type": "number",
+        "default": 60000,
+        "min": 10000,
+        "max": 3600000,
+        "group": "Connection"
+      },
+      {
+        "key": "bufferSize",
+        "label": "Buffer Size",
+        "description": "Maximum number of events to keep in memory.",
+        "type": "number",
+        "default": 200,
+        "min": 10,
+        "max": 1000,
+        "group": "Advanced"
+      }
+    ]
+  },
+  "testConnection": {
+    "url": "https://oauth.reddit.com/api/v1/me",
+    "description": "Fetches the authenticated Reddit user"
   }
 }