clawless 0.2.1 → 0.2.2

package/README.md

@@ -93,6 +93,30 @@ ACP_DEBUG_STREAM=false
 4. Copy the token provided by BotFather
 5. Paste it into your `.env` file
 
+## Authorizing Users (Whitelist)
+
+For security, the bot only accepts commands from authorized users. To configure:
+
+1. **Use your Telegram username**:
+  - You can use your Telegram username (e.g., `your_username` or `@your_username`).
+  - If you don't have a username set, you must create one in Telegram settings.
+
+2. **Add usernames to whitelist** in `~/.clawless/config.json`:
+   ```json
+   {
+     "telegramToken": "your_bot_token",
+    "telegramWhitelist": ["your_username", "another_user"]
+   }
+   ```
+
+3. **Alternative: Use environment variable**:
+   ```bash
+  # Must be a valid JSON array string
+  TELEGRAM_WHITELIST='["your_username", "another_user"]'
+   ```
+
+⚠️ **Security Note**: If `telegramWhitelist` is empty or not configured, **all users will be blocked** by default. This is a safety measure to prevent unauthorized access.
+
 ## Usage
 
 ### CLI Mode
@@ -210,6 +234,7 @@ pm2 save
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `TELEGRAM_TOKEN` | Yes | - | Your Telegram bot token from BotFather |
+| `TELEGRAM_WHITELIST` | No | [] | List of authorized Telegram usernames. **Security:** If empty, all users are blocked by default. Format: JSON array `["username1", "username2"]` |
 | `TYPING_INTERVAL_MS` | No | 4000 | Interval (in milliseconds) for refreshing Telegram typing status |
 | `GEMINI_TIMEOUT_MS` | No | 900000 | Overall timeout for a single Gemini CLI run |
 | `GEMINI_NO_OUTPUT_TIMEOUT_MS` | No | 60000 | Idle timeout; aborts if Gemini emits no output for this duration |
@@ -414,7 +439,7 @@ The codebase is designed to be simple and extensible:
 - **Never commit** `.env` file with your token (it's in `.gitignore`)
 - **Rotate tokens** if accidentally exposed
 - **Limit bot access** using Telegram's bot settings
-- **Monitor logs** for unusual activity
+- **Monitor logs** for unusual activity and unauthorized access attempts
 
 ## Contributing
 

package/bin/cli.ts

@@ -7,6 +7,7 @@ import process from 'node:process';
 
 const ENV_KEY_MAP: Record<string, string> = {
 	telegramToken: 'TELEGRAM_TOKEN',
+	telegramWhitelist: 'TELEGRAM_WHITELIST',
 	typingIntervalMs: 'TYPING_INTERVAL_MS',
 	geminiCommand: 'GEMINI_COMMAND',
 	geminiApprovalMode: 'GEMINI_APPROVAL_MODE',
@@ -34,6 +35,7 @@ const DEFAULT_AGENT_BRIDGE_HOME = path.join(os.homedir(), '.clawless');
 const DEFAULT_MEMORY_FILE_PATH = path.join(DEFAULT_AGENT_BRIDGE_HOME, 'MEMORY.md');
 const DEFAULT_CONFIG_TEMPLATE = {
 	telegramToken: 'your_telegram_bot_token_here',
+	telegramWhitelist: [],
 	typingIntervalMs: 4000,
 	geminiCommand: 'gemini',
 	geminiApprovalMode: 'yolo',
@@ -109,6 +111,9 @@ function toEnvValue(value: unknown) {
 	if (typeof value === 'string') {
 		return value;
 	}
+	if (typeof value === 'object') {
+		return JSON.stringify(value);
+	}
 	return String(value);
 }
 

package/clawless.config.example.json

@@ -1,5 +1,6 @@
 {
   "telegramToken": "your_telegram_bot_token_here",
+  "telegramWhitelist": [],
   "typingIntervalMs": 4000,
   "geminiCommand": "gemini",
   "geminiApprovalMode": "yolo",

package/dist/bin/cli.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 const ENV_KEY_MAP = {
     telegramToken: 'TELEGRAM_TOKEN',
+    telegramWhitelist: 'TELEGRAM_WHITELIST',
     typingIntervalMs: 'TYPING_INTERVAL_MS',
     geminiCommand: 'GEMINI_COMMAND',
     geminiApprovalMode: 'GEMINI_APPROVAL_MODE',
@@ -21,7 +22,7 @@ const ENV_KEY_MAP = {
     callbackPort: 'CALLBACK_PORT',
     callbackAuthToken: 'CALLBACK_AUTH_TOKEN',
     callbackMaxBodyBytes: 'CALLBACK_MAX_BODY_BYTES',
-    agentBridgeHome: 'AGENT_BRIDGE_HOME',
+    ClawlessHome: 'AGENT_BRIDGE_HOME',
     memoryFilePath: 'MEMORY_FILE_PATH',
     memoryMaxChars: 'MEMORY_MAX_CHARS',
     schedulesFilePath: 'SCHEDULES_FILE_PATH',
@@ -31,6 +32,7 @@ const DEFAULT_AGENT_BRIDGE_HOME = path.join(os.homedir(), '.clawless');
 const DEFAULT_MEMORY_FILE_PATH = path.join(DEFAULT_AGENT_BRIDGE_HOME, 'MEMORY.md');
 const DEFAULT_CONFIG_TEMPLATE = {
     telegramToken: 'your_telegram_bot_token_here',
+    telegramWhitelist: [],
     typingIntervalMs: 4000,
     geminiCommand: 'gemini',
     geminiApprovalMode: 'yolo',
@@ -47,7 +49,7 @@ const DEFAULT_CONFIG_TEMPLATE = {
     callbackPort: 8788,
     callbackAuthToken: '',
     callbackMaxBodyBytes: 65536,
-    agentBridgeHome: '~/.clawless',
+    ClawlessHome: '~/.clawless',
     memoryFilePath: '~/.clawless/MEMORY.md',
     memoryMaxChars: 12000,
     schedulesFilePath: '~/.clawless/schedules.json',
@@ -98,6 +100,9 @@ function toEnvValue(value) {
     if (typeof value === 'string') {
         return value;
     }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
     return String(value);
 }
 function resolveEnvKey(configKey) {

package/dist/index.js

@@ -48,6 +48,35 @@ const TYPING_INTERVAL_MS = parseInt(process.env.TYPING_INTERVAL_MS || '4000', 10
 const TELEGRAM_STREAM_UPDATE_INTERVAL_MS = 1000;
 // Maximum response length to prevent memory issues (Telegram has 4096 char limit anyway)
 const MAX_RESPONSE_LENGTH = parseInt(process.env.MAX_RESPONSE_LENGTH || '4000', 10);
+// Parse Telegram whitelist from environment variable
+// Expected format: JSON array of usernames (e.g., ["user1", "user2"])
+function parseWhitelistFromEnv(envValue) {
+    if (!envValue || envValue.trim() === '') {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(envValue);
+        if (Array.isArray(parsed)) {
+            return parsed.map((name) => String(name).trim().replace(/^@/, '')).filter(Boolean);
+        }
+    }
+    catch {
+        console.warn('Warning: TELEGRAM_WHITELIST must be a valid JSON array of usernames (e.g., ["user1", "user2"])');
+    }
+    return [];
+}
+const TELEGRAM_WHITELIST = parseWhitelistFromEnv(process.env.TELEGRAM_WHITELIST || '');
+function isUserAuthorized(username) {
+    // If whitelist is empty, block all users by default (safe default)
+    if (TELEGRAM_WHITELIST.length === 0) {
+        return false;
+    }
+    if (!username) {
+        return false;
+    }
+    const normalizedUsername = username.toLowerCase();
+    return TELEGRAM_WHITELIST.some(entry => entry.toLowerCase() === normalizedUsername);
+}
 const messagingClient = new TelegramMessagingClient({
     token: process.env.TELEGRAM_TOKEN,
     typingIntervalMs: TYPING_INTERVAL_MS,
@@ -68,7 +97,7 @@ const GEMINI_STDERR_TAIL_MAX = 4000;
 function validateGeminiCommandOrExit() {
     const result = spawnSync(GEMINI_COMMAND, ['--version'], {
         stdio: 'ignore',
-        timeout: 5000,
+        timeout: 10000,
         killSignal: 'SIGKILL',
     });
     if (result.error?.code === 'ENOENT') {
@@ -492,9 +521,9 @@ function ensureMemoryFile() {
     fs.mkdirSync(path.dirname(MEMORY_FILE_PATH), { recursive: true });
     if (!fs.existsSync(MEMORY_FILE_PATH)) {
         const template = [
-            '# Gemini Bridge Memory',
+            '# Clawless Memory',
             '',
-            'This file stores durable memory notes for Gemini Bridge.',
+            'This file stores durable memory notes for Clawless.',
             '',
             '## Notes',
             '',
@@ -1034,6 +1063,12 @@ async function processSingleMessage(messageContext, messageRequestId) {
  * Handles incoming text messages from Telegram
  */
 messagingClient.onTextMessage(async (messageContext) => {
+    // Check if user is authorized
+    if (!isUserAuthorized(messageContext.username)) {
+        console.warn(`Unauthorized access attempt from username: ${messageContext.username ?? 'none'} (ID: ${messageContext.userId ?? 'unknown'})`);
+        await messageContext.sendText('🚫 Unauthorized. This bot is restricted to authorized users only.');
+        return;
+    }
     if (messageContext.chatId !== undefined && messageContext.chatId !== null) {
         lastIncomingChatId = String(messageContext.chatId);
         persistCallbackChatId(lastIncomingChatId);
@@ -1092,7 +1127,15 @@ messagingClient.launch()
         callbackPort: CALLBACK_PORT,
         mcpSkillsSource: 'local Gemini CLI defaults (no MCP override)',
         acpMode: `${GEMINI_COMMAND} --experimental-acp`,
+        telegramWhitelist: TELEGRAM_WHITELIST.length > 0 ? `${TELEGRAM_WHITELIST.length} user(s) authorized` : 'NONE (all users blocked)',
     });
+    if (TELEGRAM_WHITELIST.length === 0) {
+        console.warn('⚠️  WARNING: Telegram whitelist is empty. All users will be blocked.');
+        console.warn('⚠️  Add usernames to TELEGRAM_WHITELIST config (as a JSON array) to authorize users.');
+    }
+    else {
+        console.log(`✅ Telegram authorization enabled. Authorized usernames: ${TELEGRAM_WHITELIST.join(', ')}`);
+    }
     scheduleAcpPrewarm('post-launch');
     if (HEARTBEAT_INTERVAL_MS > 0) {
         setInterval(() => {

package/dist/messaging/telegramClient.js

@@ -22,12 +22,16 @@ class TelegramMessageContext {
     maxMessageLength;
     text;
     chatId;
+    userId;
+    username;
     constructor(ctx, typingIntervalMs, maxMessageLength) {
         this.ctx = ctx;
         this.typingIntervalMs = typingIntervalMs;
         this.maxMessageLength = maxMessageLength;
         this.text = ctx.message?.text || '';
         this.chatId = ctx.chat?.id;
+        this.userId = ctx.from?.id;
+        this.username = ctx.from?.username;
     }
     startTyping() {
         this.ctx.telegram.sendChatAction(this.ctx.chat.id, 'typing').catch(() => { });

package/index.ts

@@ -55,6 +55,42 @@ const TELEGRAM_STREAM_UPDATE_INTERVAL_MS = 1000;
 // Maximum response length to prevent memory issues (Telegram has 4096 char limit anyway)
 const MAX_RESPONSE_LENGTH = parseInt(process.env.MAX_RESPONSE_LENGTH || '4000', 10);
 
+// Parse Telegram whitelist from environment variable
+// Expected format: JSON array of usernames (e.g., ["user1", "user2"])
+function parseWhitelistFromEnv(envValue: string): string[] {
+  if (!envValue || envValue.trim() === '') {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(envValue);
+    if (Array.isArray(parsed)) {
+      return parsed.map((name) => String(name).trim().replace(/^@/, '')).filter(Boolean);
+    }
+  } catch {
+    console.warn('Warning: TELEGRAM_WHITELIST must be a valid JSON array of usernames (e.g., ["user1", "user2"])');
+  }
+
+  return [];
+}
+
+const TELEGRAM_WHITELIST: string[] = parseWhitelistFromEnv(process.env.TELEGRAM_WHITELIST || '');
+
+function isUserAuthorized(username: string | undefined): boolean {
+  // If whitelist is empty, block all users by default (safe default)
+  if (TELEGRAM_WHITELIST.length === 0) {
+    return false;
+  }
+
+  if (!username) {
+    return false;
+  }
+
+  const normalizedUsername = username.toLowerCase();
+
+  return TELEGRAM_WHITELIST.some(entry => entry.toLowerCase() === normalizedUsername);
+}
+
 const messagingClient = new TelegramMessagingClient({
   token: process.env.TELEGRAM_TOKEN,
   typingIntervalMs: TYPING_INTERVAL_MS,
@@ -77,7 +113,7 @@ const GEMINI_STDERR_TAIL_MAX = 4000;
 function validateGeminiCommandOrExit() {
   const result = spawnSync(GEMINI_COMMAND, ['--version'], {
     stdio: 'ignore',
-    timeout: 5000,
+    timeout: 10000,
     killSignal: 'SIGKILL',
   });
 
@@ -1182,6 +1218,13 @@ async function processSingleMessage(messageContext: any, messageRequestId: numbe
  * Handles incoming text messages from Telegram
  */
 messagingClient.onTextMessage(async (messageContext) => {
+  // Check if user is authorized
+  if (!isUserAuthorized(messageContext.username)) {
+    console.warn(`Unauthorized access attempt from username: ${messageContext.username ?? 'none'} (ID: ${messageContext.userId ?? 'unknown'})`);
+    await messageContext.sendText('🚫 Unauthorized. This bot is restricted to authorized users only.');
+    return;
+  }
+
   if (messageContext.chatId !== undefined && messageContext.chatId !== null) {
     lastIncomingChatId = String(messageContext.chatId);
     persistCallbackChatId(lastIncomingChatId);
@@ -1246,8 +1289,16 @@ messagingClient.launch()
       callbackPort: CALLBACK_PORT,
       mcpSkillsSource: 'local Gemini CLI defaults (no MCP override)',
       acpMode: `${GEMINI_COMMAND} --experimental-acp`,
+      telegramWhitelist: TELEGRAM_WHITELIST.length > 0 ? `${TELEGRAM_WHITELIST.length} user(s) authorized` : 'NONE (all users blocked)',
     });
 
+    if (TELEGRAM_WHITELIST.length === 0) {
+      console.warn('⚠️  WARNING: Telegram whitelist is empty. All users will be blocked.');
+      console.warn('⚠️  Add usernames to TELEGRAM_WHITELIST config (as a JSON array) to authorize users.');
+    } else {
+      console.log(`✅ Telegram authorization enabled. Authorized usernames: ${TELEGRAM_WHITELIST.join(', ')}`);
+    }
+
     scheduleAcpPrewarm('post-launch');
 
     if (HEARTBEAT_INTERVAL_MS > 0) {

package/messaging/telegramClient.ts

@@ -28,6 +28,8 @@ class TelegramMessageContext {
   maxMessageLength: number;
   text: string;
   chatId: string | number | undefined;
+  userId: number | undefined;
+  username: string | undefined;
 
   constructor(ctx: any, typingIntervalMs: number, maxMessageLength: number) {
     this.ctx = ctx;
@@ -35,6 +37,8 @@ class TelegramMessageContext {
     this.maxMessageLength = maxMessageLength;
     this.text = ctx.message?.text || '';
     this.chatId = ctx.chat?.id;
+    this.userId = ctx.from?.id;
+    this.username = ctx.from?.username;
   }
 
   startTyping() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawless",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A bridge connecting Telegram to Agent Gemini CLI using Agent Communication Protocol (ACP)",
   "main": "dist/index.js",
   "type": "module",