alvin-bot 4.12.1 → 4.12.2

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.12.2] — 2026-04-15
+
+### 🔒 Security patch: file permissions, ALLOWED_USERS hard-fail, exec-guard hardening, CVE updates
+
+This is the first **formal security release** of Alvin Bot, motivated by a comprehensive audit after v4.12.1 production deployment. The audit surfaced real issues that needed fixing before the bot could be safely installed on multi-user dev servers or shared by external users. All fixes are additive and backwards-compatible — existing single-user installs see no behavior change except improved security.
+
+#### CRITICAL CVE — axios 1.14.0 → 1.15.0 (CVSS 10.0)
+
+Transitive dependency via `@slack/bolt`. Two CVEs closed:
+- GHSA-fvcv-3m26-pcqx — Cloud Metadata Exfiltration via Header Injection Chain (CVSS 10.0)
+- GHSA-3p68-rc4w-qgx5 — NO_PROXY Hostname Normalization Bypass → SSRF
+
+Fix: `npm update @slack/bolt` (4.6.0 → 4.7.0) + `package.json overrides: axios ^1.15.0` to force transitive updates in `@slack/web-api` and `@whiskeysockets/baileys`. Post-fix `npm audit` shows **0 critical, 2 high remaining** (`basic-ftp` HIGH — never invoked by Alvin, `electron` HIGH — devDep only, tracked as Phase 18).
+
+Also updated `@anthropic-ai/claude-agent-sdk` 0.2.97 → 0.2.109 (MODERATE: GHSA-5474-4w2j-mq4c Path Validation Sandbox Escape).
+
+#### CRITICAL — File permissions on sensitive files (0o600)
+
+Pre-v4.12.2 `~/.alvin-bot/.env`, `state/sessions.json`, memory logs, cron-jobs.json were written with the default umask — typically 0o644 on Linux/macOS, meaning any other user on the same machine could read BOT_TOKEN + all API keys, full conversation history, cron prompts, and encrypted sudo credentials.
+
+**Fix**: new `src/services/file-permissions.ts` with `writeSecure()`, `ensureSecureMode()`, `auditSensitiveFiles()`. All `.env` writes in setup-api, doctor-api, server, fallback-order, session-persistence now use `writeSecure()`. Startup audit in `index.ts` chmod-repairs the full sensitive-file list idempotently on every boot.
+
+#### CRITICAL — ALLOWED_USERS startup hard-fail
+
+Pre-v4.12.2 Alvin started with BOT_TOKEN set but ALLOWED_USERS empty with only a console.warn — leaving the bot "configured but unguarded".
+
+**Fix**: new pure gate function `src/services/allowed-users-gate.ts`. `src/index.ts` refuses to start with a clear error message. Two explicit escape hatches: `AUTH_MODE=open` or `ALVIN_INSECURE_ACKNOWLEDGED=1`.
+
+#### HIGH — Webhook bearer token timing-safe comparison
+
+`src/web/server.ts` POST /api/webhook previously used naive `authHeader !== "Bearer " + token` leaking comparison position via timing side-channel.
+
+**Fix**: new `src/services/timing-safe-bearer.ts` wraps `crypto.timingSafeEqual` with strict "Bearer <token>" format, empty-expected rejection, length-mismatch dummy comparison.
+
+#### HIGH — Exec-guard shell metacharacter rejection
+
+`checkExecAllowed()` only inspected the first word — `echo safe; rm -rf /` passed as "echo". Trivially bypassable via `&&`, `|`, `` ` ``, `$(...)`, redirects.
+
+**Fix**: allowlist mode rejects any command containing `;`, `&`, `|`, `` ` ``, `$(...)`, `{...}`, `<`, `>`. Operators who need shell pipelines set `EXEC_SECURITY=full` explicitly.
+
+#### HIGH — Cron shell-job execGuard integration
+
+Pre-v4.12.2 cron `type: "shell"` bypassed the exec-guard entirely. **Fix**: cron.ts case "shell" now calls `checkExecAllowed()` before `execSync()` and sends a blocked-notification on deny.
+
+#### MEDIUM — Sub-agent toolset allowlist (readonly, research)
+
+`SubAgentConfig.toolset` widened from `"full"` to `"full" | "readonly" | "research"`:
+- `readonly` → Read, Glob, Grep only (no write, shell, network)
+- `research` → readonly + WebSearch, WebFetch
+- `full` → unchanged default
+
+New `QueryOptions.allowedTools?: string[]` honored by `claude-sdk-provider`. Other providers ignore it.
+
+#### NEW — `docs/security.md` threat model + hardening guide (279 lines)
+
+First formal security documentation covering: TL;DR safety table, capability surface, attacker model, trust boundaries, hardening step-by-step, shell execution policy, file permissions list, sub-agent presets, prompt injection honesty section, Phase 18 pending work, security issue reporting, incident response playbook. Public doc, shipped with the repo.
+
+#### NEW — README Security section rewrite
+
+Replaced thin bullet list with a boxed warning ("Alvin has full shell + filesystem access") and four sub-sections: access control, execution hardening, data hardening, known limitations. Links to docs/security.md.
+
+#### Testing
+
+**396 tests total** (350 baseline from v4.12.1 + 46 new). All green. Build clean.
+
+- 10 `test/file-permissions.test.ts`
+- 7 `test/allowed-users-gate.test.ts`
+- 10 `test/timing-safe-bearer.test.ts`
+- 13 `test/exec-guard-metachars.test.ts`
+- 4 `test/subagent-toolset-allowlist.test.ts`
+- 2 extended `test/subagents-toolset.test.ts` (readonly + research)
+
+#### Phase 18 (deferred, tracked in README Roadmap)
+
+- Electron 35 → 41+ upgrade (Desktop build, 6 CVEs)
+- Prompt injection defense strategy (design debate, not code filter)
+- TypeScript 5 → 6 upgrade
+- MCP plugin sandboxing (architectural v5.0)
+
+---
+
 ## [4.12.1] — 2026-04-15
 
 ### 🐛 Patch: Sync sub-agent timeout + workspace command menu

package/README.md

@@ -659,17 +659,54 @@ alvin-bot version   # Show version
   - [ ] Workspace cloning / templates — `/workspace clone alev-b as homes-dev` spins up a new workspace from an existing one
   - [ ] Slack slash commands (`/alvin workspace`, `/alvin status`, `/alvin new`) — native Slack command integration via Bolt
   - [ ] Daily log decay / archive — older daily logs move to cold storage after N days
+- [ ] **Phase 18** — Security + Platform hardening (from v4.12.1 audit, prioritized)
+  - [ ] **P1 — Electron major upgrade** (35 → 41+) — fixes 1 HIGH + 5 MODERATE Electron CVEs in the Desktop-Build path. Major version jump, requires full rebuild + test of `.dmg` flow. Separate release (likely bundled with Windows `.exe` work).
+  - [ ] **P1 — Prompt injection defense strategy** — not a single fix but a design debate: heuristic filters vs allow-list vs no-sandbox-accept-the-risk. Currently handled as a documented design-constraint (README security section), not as a code filter. When we decide the policy, implement it across all message entry points.
+  - [ ] **P2 — TypeScript 5 → 6 upgrade** — major release, likely breaking changes in strict mode. Needs a dedicated release + test sweep. Low priority since 5.x is still supported.
+  - [ ] **P0 for v5.0 — MCP plugin sandboxing** — currently MCP servers run with full Node privileges. Plan: run each MCP in a child process with restricted FS + network policy (similar to deno-permission model). Architectural change, v5.0 territory.
 
 ---
 
 ## 🔒 Security
 
-- **User whitelist** — Only `ALLOWED_USERS` can interact with the bot
+> ### ⚠️ Important: Alvin has full shell + filesystem access
+>
+> Alvin Bot is an **autonomous AI agent** built on the Claude Agent SDK with shell, filesystem, and network access to the machine it runs on. This is by design — it's the point of the project. But it means:
+>
+> - **Treat the bot like `sudo` access** — only install it on machines where you'd trust Claude Code to run without supervision.
+> - **Never expose the Web UI (port 3100) to the internet** without HTTPS, rate limiting, and a strong `WEB_PASSWORD`. It binds to `localhost` by default.
+> - **On multi-user systems**, verify `~/.alvin-bot/.env` is chmod `600` (v4.12.2+ enforces this automatically on startup).
+> - **`ALLOWED_USERS` is your first line of defense** — v4.12.2+ refuses to start if it's empty and Telegram is enabled.
+>
+> **Read the full threat model and hardening guide:** [`docs/security.md`](docs/security.md)
+
+### Access control
+
+- **User whitelist** — Only `ALLOWED_USERS` can interact with the bot (hard-enforced at startup since v4.12.2)
 - **WhatsApp group approval** — Per-group participant whitelist + owner approval gate via Telegram (with WhatsApp DM / Discord / Signal fallback). Group members never see the approval process.
-- **Self-hosted** — Your data stays on your machine
-- **No telemetry** — Zero tracking, zero analytics, zero phone-home
-- **Web UI auth** — Optional password protection for the dashboard
-- **Owner protection** — Owner account cannot be deleted via UI
+- **Slack allowlist** — `SLACK_ALLOWED_USERS` restricts who can DM or @mention the bot in Slack
+- **DM pairing** — Optional 6-digit code flow for new users via owner approval (`AUTH_MODE=pairing`)
+
+### Execution hardening
+
+- **`EXEC_SECURITY=allowlist`** (default) — Shell commands must match a whitelist of safe binaries and **cannot contain shell metacharacters** (`;`, `|`, `&`, `` ` ``, `$(...)`, redirects). Rejected by v4.12.2's exec-guard metachar filter.
+- **Cron shell jobs** go through the same exec-guard (v4.12.2+) — cron is no longer a bypass vector.
+- **Sub-agent toolset presets** — spawn sub-agents with `toolset: "readonly"` or `"research"` to restrict what they can do, regardless of the parent's privileges.
+- **Timing-safe webhook auth** — `POST /api/webhook` uses `crypto.timingSafeEqual` (v4.12.2+) to prevent timing side-channel token extraction.
+
+### Data hardening
+
+- **Self-hosted** — Your data stays on your machine. No cloud sync, no external logging of prompts or responses.
+- **No telemetry** — Zero tracking, zero analytics, zero phone-home.
+- **File permissions** — `.env`, `sessions.json`, memory logs, cron jobs, and all sensitive state files are chmod `0o600` on every write and repaired at startup (v4.12.2+).
+- **Owner protection** — Owner account cannot be deleted via UI.
+- **Encrypted sudo credentials** — If you enable sudo exec, passwords are stored encrypted with an XOR key in a separate file, both chmod `0o600`.
+
+### Known limitations (documented honestly)
+
+- **Prompt injection** cannot be reliably filtered — we document this as a capability tradeoff rather than pretending to solve it. See `docs/security.md` for the full discussion.
+- **Not yet hardened for public-internet deployment** — current scope is "on your own machine". VPS deployment works but requires additional reverse-proxy + TLS + rate-limit setup that we don't automate.
+- **Electron Desktop build** has known CVEs (Phase 18 roadmap). The primary distribution is npm global install, not Desktop — if you don't use the Desktop wrapper, you're not affected.
 
 ---
 

package/dist/index.js

@@ -20,6 +20,57 @@ if (hasLegacyData()) {
 }
 // 3. Seed defaults for any files that don't exist yet (fresh install)
 seedDefaults();
+// 3a. v4.12.2 — Audit + repair permissions on sensitive files. On multi-user
+//     systems, files written pre-v4.12.2 may have 0o644 / 0o666 mode — i.e.
+//     readable by other users on the same machine. This routine chmod-repairs
+//     them to 0o600 (owner read/write only) at every startup. Idempotent for
+//     already-secure files; silent no-op for missing files.
+import { auditSensitiveFiles } from "./services/file-permissions.js";
+import { ENV_FILE as SEC_ENV, SESSIONS_STATE_FILE, MEMORY_FILE, CRON_FILE as SEC_CRON } from "./paths.js";
+import { readdirSync } from "fs";
+import { resolve as pathResolve } from "path";
+import { MEMORY_DIR as SEC_MEM_DIR, DATA_DIR as SEC_DATA_DIR } from "./paths.js";
+{
+    const sensitivePaths = [SEC_ENV, SESSIONS_STATE_FILE, MEMORY_FILE, SEC_CRON];
+    // Also audit every daily-log markdown file — they contain full conversation history
+    try {
+        if (readdirSync.length !== undefined) {
+            for (const entry of readdirSync(SEC_MEM_DIR)) {
+                if (entry.endsWith(".md") && !entry.startsWith(".")) {
+                    sensitivePaths.push(pathResolve(SEC_MEM_DIR, entry));
+                }
+            }
+        }
+    }
+    catch {
+        // memory dir missing — fine
+    }
+    // Also include async-agents state, delivery queue, and sudo credentials
+    const optionalPaths = [
+        pathResolve(SEC_DATA_DIR, "state", "async-agents.json"),
+        pathResolve(SEC_DATA_DIR, "delivery-queue.json"),
+        pathResolve(SEC_DATA_DIR, "data", ".sudo-enc"),
+        pathResolve(SEC_DATA_DIR, "data", ".sudo-key"),
+        pathResolve(SEC_DATA_DIR, "data", "access.json"),
+        pathResolve(SEC_DATA_DIR, "data", "approved-users.json"),
+    ];
+    sensitivePaths.push(...optionalPaths);
+    const auditResults = auditSensitiveFiles(sensitivePaths);
+    const repaired = auditResults.filter(r => r.status === "repaired");
+    if (repaired.length > 0) {
+        console.log(`🔒 file-permissions: repaired ${repaired.length} sensitive file(s) to 0o600`);
+        for (const r of repaired) {
+            console.log(`   ${r.path} (was 0o${r.previousMode})`);
+        }
+    }
+    const errors = auditResults.filter(r => r.status === "error");
+    if (errors.length > 0) {
+        console.warn(`⚠️  file-permissions: ${errors.length} file(s) could not be repaired:`);
+        for (const r of errors) {
+            console.warn(`   ${r.path}: ${r.error}`);
+        }
+    }
+}
 // 4. Crash-loop brake check — if we've crashed N times in a short window,
 //    refuse to start, write an alert file, and unload our LaunchAgent so
 //    launchd stops retrying. Runs BEFORE any expensive init so a broken
@@ -35,9 +86,30 @@ if (!hasTelegram) {
     console.warn("⚠️  BOT_TOKEN not set — Telegram disabled. WebUI + Cron still active.");
     console.warn("   Run 'alvin-bot setup' or set BOT_TOKEN in ~/.alvin-bot/.env");
 }
-if (config.allowedUsers.length === 0 && hasTelegram) {
-    console.warn("⚠️  ALLOWED_USERS not set — nobody can message the Telegram bot yet.");
-    console.warn("   Send /start to @userinfobot on Telegram to find your ID.");
+// v4.12.2 — ALLOWED_USERS startup gate. Refuses to start when Telegram is
+// configured but no user allowlist is set, because that would leave the bot
+// open to any Telegram user with full shell/filesystem access via prompt
+// injection. See src/services/allowed-users-gate.ts for the pure decision
+// function + tests.
+{
+    const { checkAllowedUsersGate } = await import("./services/allowed-users-gate.js");
+    const gate = checkAllowedUsersGate({
+        hasTelegram,
+        allowedUsersCount: config.allowedUsers.length,
+        authMode: config.authMode,
+        insecureAcknowledged: process.env.ALVIN_INSECURE_ACKNOWLEDGED === "1",
+    });
+    if (!gate.allowed) {
+        console.error("");
+        console.error("❌ CRITICAL: Alvin Bot refusing to start.");
+        console.error("");
+        console.error("   " + gate.reason);
+        console.error("");
+        process.exit(1);
+    }
+    if (gate.warning) {
+        console.warn("⚠️  " + gate.warning);
+    }
 }
 // Check if the chosen provider has a corresponding API key.
 // Keys here MUST match the registry keys from src/providers/registry.ts

package/dist/providers/claude-sdk-provider.js

@@ -114,7 +114,10 @@ export class ClaudeSDKProvider {
                     allowDangerouslySkipPermissions: true,
                     env: cleanEnv,
                     settingSources: ["user", "project"],
-                    allowedTools: [
+                    // v4.12.2 — options.allowedTools can override the default full set.
+                    // Used by sub-agents with toolset="readonly"/"research" to restrict
+                    // what Claude can do. Default = full access.
+                    allowedTools: options.allowedTools ?? [
                         "Read", "Write", "Edit", "Bash", "Glob", "Grep",
                         "WebSearch", "WebFetch", "Task",
                     ],

package/dist/services/allowed-users-gate.js

@@ -0,0 +1,56 @@
+/**
+ * ALLOWED_USERS Startup Gate (v4.12.2)
+ *
+ * Pure decision function that runs at startup to decide whether Alvin should
+ * refuse to start because its Telegram bot is configured but has no user
+ * allowlist.
+ *
+ * Before v4.12.2, an empty ALLOWED_USERS with AUTH_MODE=allowlist would only
+ * emit a console.warn and the bot would start anyway. On production this
+ * left a "configured but unguarded" surface — any Telegram user who sends
+ * a DM would reach the bot and could exploit shell/filesystem access via
+ * prompt injection.
+ *
+ * The gate has two explicit escape hatches, both intentional:
+ *   1. AUTH_MODE=open — user explicitly wants a public bot (not recommended)
+ *   2. ALVIN_INSECURE_ACKNOWLEDGED=1 — explicit operator opt-out used for
+ *      test environments and scripted installs where the operator
+ *      acknowledges they know what they're doing.
+ *
+ * Pure: takes config values as args, returns a decision. The actual
+ * process.exit(1) lives in src/index.ts as a thin wrapper.
+ */
+export function checkAllowedUsersGate(input) {
+    // WebUI-only deployments don't have a BOT_TOKEN → nothing to gate
+    if (!input.hasTelegram) {
+        return { allowed: true };
+    }
+    // Telegram is enabled AND allowlist is populated → normal path
+    if (input.allowedUsersCount > 0) {
+        return { allowed: true };
+    }
+    // Telegram enabled but allowlist empty — check escape hatches
+    if (input.authMode === "open") {
+        return {
+            allowed: true,
+            warning: "AUTH_MODE=open explicitly set. Any Telegram user can message the bot. " +
+                "This is NOT recommended for machines with sensitive files or shell access.",
+        };
+    }
+    if (input.insecureAcknowledged) {
+        return {
+            allowed: true,
+            warning: "ALVIN_INSECURE_ACKNOWLEDGED=1 set. Bot starts with empty ALLOWED_USERS. " +
+                "The operator has explicitly opted out of the safety gate.",
+        };
+    }
+    // No escape hatch — refuse to start
+    return {
+        allowed: false,
+        reason: "ALLOWED_USERS is empty but BOT_TOKEN is set. " +
+            "Alvin Bot has full shell/filesystem access on this machine, so starting with " +
+            "an empty allowlist would leave the bot open to anyone who sends it a Telegram message. " +
+            "Fix: set ALLOWED_USERS=<your telegram user id> in ~/.alvin-bot/.env (get your ID from @userinfobot). " +
+            "Explicit opt-out: AUTH_MODE=open OR ALVIN_INSECURE_ACKNOWLEDGED=1.",
+    };
+}

package/dist/services/cron.js

@@ -124,6 +124,23 @@ async function executeJob(job) {
             }
             case "shell": {
                 const cmd = job.payload.command || "echo 'no command'";
+                // v4.12.2 — Cron shell jobs now go through exec-guard. Before
+                // v4.12.2 cron bypassed the allowlist, which was inconsistent
+                // with the rest of the bot's shell execution policy. With
+                // EXEC_SECURITY=allowlist (default) this rejects jobs with
+                // shell metacharacters or non-allowlisted binaries. Operators
+                // who legitimately need complex shell pipelines in cron set
+                // EXEC_SECURITY=full explicitly.
+                const { checkExecAllowed } = await import("./exec-guard.js");
+                const guard = checkExecAllowed(cmd);
+                if (!guard.allowed) {
+                    const msg = `Cron shell job blocked by exec-guard: ${guard.reason}`;
+                    console.warn(`[cron] ${job.name}: ${msg}`);
+                    if (notifyCallback) {
+                        await notifyCallback(job.target, `🛑 ${job.name}\n${msg}\n\nSet EXEC_SECURITY=full if this is intentional.`);
+                    }
+                    return { output: msg };
+                }
                 // Per-job timeout, default = no timeout (execSync treats timeout=0
                 // or "undefined" as infinite). Users opt in via /cron add … --timeout N.
                 const shellOpts = {

package/dist/services/exec-guard.js

@@ -30,12 +30,37 @@ function extractBinary(command) {
     // Strip path: /usr/bin/curl -> curl
     return first.split("/").pop() || first;
 }
+/**
+ * v4.12.2 — Reject shell metacharacters in allowlist mode.
+ *
+ * The pre-v4.12.2 allowlist check only inspected the first word of the
+ * command. That was trivially bypassable via:
+ *   - ";" chaining:       "echo safe; rm -rf /"
+ *   - "&&" / "||" chains:  "echo hi && cat /etc/passwd"
+ *   - pipe:                "cat /etc/passwd | head"
+ *   - substitution:        "echo $(whoami)" or "`whoami`"
+ *   - redirect:            "echo hi > /etc/passwd"
+ *   - backgrounding:       "... &"
+ *
+ * Strategy: in allowlist mode, any command containing any of these
+ * metachars is rejected outright. Users who need shell pipelines opt in
+ * explicitly via EXEC_SECURITY=full.
+ */
+const SHELL_METACHAR_PATTERN = /[;&|`$(){}<>]/;
 export function checkExecAllowed(command) {
     if (config.execSecurity === "full")
         return { allowed: true };
     if (config.execSecurity === "deny")
         return { allowed: false, reason: "Shell execution is disabled" };
-    // allowlist mode
+    // allowlist mode — v4.12.2 metachar guard
+    if (SHELL_METACHAR_PATTERN.test(command)) {
+        return {
+            allowed: false,
+            reason: `Command contains shell metacharacters (pipes, redirects, substitution, chaining). ` +
+                `Allowlist mode only permits simple binary invocations. ` +
+                `Set EXEC_SECURITY=full if you need shell pipelines.`,
+        };
+    }
     const binary = extractBinary(command);
     if (SAFE_BINS.includes(binary))
         return { allowed: true };

package/dist/services/fallback-order.js

@@ -10,6 +10,7 @@
  */
 import fs from "fs";
 import { FALLBACK_FILE, ENV_FILE, DATA_DIR } from "../paths.js";
+import { writeSecure } from "./file-permissions.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Get the current fallback order.
@@ -143,7 +144,9 @@ function syncToEnv(primary, fallbacks) {
         else {
             env += `\nFALLBACK_PROVIDERS=${fallbackStr}`;
         }
-        fs.writeFileSync(ENV_FILE, env);
+        // v4.12.2 — writeSecure enforces 0o600 on .env so other users on the
+        // machine can't read tokens/API keys.
+        writeSecure(ENV_FILE, env);
     }
     catch (err) {
         console.error("Failed to sync fallback order to .env:", err);

package/dist/services/file-permissions.js

@@ -0,0 +1,93 @@
+/**
+ * File Permissions Hardening (v4.12.2)
+ *
+ * On multi-user dev servers, Alvin's sensitive files (.env, sessions.json,
+ * memory files, cron-jobs.json) were previously written with the default
+ * umask — typically 0o644 on Linux/macOS, meaning any other user on the
+ * same machine could read API keys, conversation history, cron job
+ * definitions, etc.
+ *
+ * This module provides:
+ *   - writeSecure(path, content) — atomic write with mode 0o600
+ *   - ensureSecureMode(path) — chmod-repair an existing file if it's too permissive
+ *   - auditSensitiveFiles(paths[]) — batch-audit a list of files and repair
+ *
+ * The handler strategy:
+ *   - NEW writes: use writeSecure() or pass `{ mode: 0o600 }` to writeFileSync
+ *   - STARTUP: call auditSensitiveFiles() once with the list of known-sensitive
+ *     files to chmod-repair anything that was written pre-v4.12.2
+ *
+ * Pure file-system operations — no grammy, no session, testable in isolation.
+ */
+import fs from "fs";
+/** Strict mode for all sensitive files: owner read/write only. */
+export const SECURE_MODE = 0o600;
+/**
+ * Atomically write a file with mode 0o600.
+ *
+ * Uses fs.writeFileSync's built-in `mode` option for initial creation, then
+ * an explicit fs.chmodSync to handle the case where the file already exists
+ * (in which case the mode arg to writeFileSync is ignored).
+ */
+export function writeSecure(path, content) {
+    fs.writeFileSync(path, content, { mode: SECURE_MODE });
+    // writeFileSync's mode is only applied on initial create. If the file
+    // already existed with a looser mode, we need to explicitly chmod it.
+    try {
+        fs.chmodSync(path, SECURE_MODE);
+    }
+    catch {
+        // Best effort — some filesystems (e.g. FAT) don't support chmod
+    }
+}
+/**
+ * Ensure a file is at most as permissive as SECURE_MODE (0o600). If it's
+ * already 0o600 or stricter (e.g. 0o400), leave it alone. If it's more
+ * permissive (e.g. 0o644, 0o666), repair it to 0o600.
+ *
+ * Returns a report of what happened — used by auditSensitiveFiles().
+ */
+export function ensureSecureMode(path) {
+    let stat;
+    try {
+        stat = fs.statSync(path);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { path, status: "missing" };
+        }
+        return { path, status: "error", error: e.message };
+    }
+    const currentMode = stat.mode & 0o777;
+    // If the file is already at SECURE_MODE or stricter (fewer bits), leave it.
+    // We use bitwise AND: if (currentMode & ~SECURE_MODE) === 0 then all set bits
+    // are within SECURE_MODE's bits — i.e. the file is not MORE permissive.
+    if ((currentMode & ~SECURE_MODE) === 0) {
+        return { path, status: "already-secure" };
+    }
+    // File is more permissive than 0o600 — repair.
+    try {
+        fs.chmodSync(path, SECURE_MODE);
+        return {
+            path,
+            status: "repaired",
+            previousMode: currentMode.toString(8),
+        };
+    }
+    catch (err) {
+        return {
+            path,
+            status: "error",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Audit + repair a list of sensitive file paths. Returns a report per file.
+ * Called once at bot startup with the list of known-sensitive files so that
+ * any file written pre-v4.12.2 (with default 0o644/0o666 umask) gets repaired.
+ */
+export function auditSensitiveFiles(paths) {
+    return paths.map(p => ensureSecureMode(p));
+}

package/dist/services/session-persistence.js

@@ -21,6 +21,7 @@
 import fs from "fs";
 import { dirname } from "path";
 import { SESSIONS_STATE_FILE } from "../paths.js";
+import { SECURE_MODE } from "./file-permissions.js";
 import { getAllSessions, getTelegramWorkspacesMap, } from "./session.js";
 /** History entries to keep in the persisted snapshot (per session). */
 const MAX_PERSISTED_HISTORY = 50;
@@ -85,9 +86,20 @@ export async function flushSessions() {
             sessions: out,
             telegramWorkspaces: tgWorkspaces,
         };
-        // Atomic write: tmp + rename
+        // Atomic write: tmp + rename. v4.12.2 — mode 0o600 enforced so other
+        // users on the same machine can't read conversation history or tokens.
         const tmpFile = `${SESSIONS_STATE_FILE}.tmp`;
-        fs.writeFileSync(tmpFile, JSON.stringify(envelope, null, 2), "utf-8");
+        fs.writeFileSync(tmpFile, JSON.stringify(envelope, null, 2), {
+            encoding: "utf-8",
+            mode: SECURE_MODE,
+        });
+        // Belt-and-suspenders: chmod in case the tmp file already existed with
+        // looser permissions (writeFileSync's mode option is only applied on
+        // initial create).
+        try {
+            fs.chmodSync(tmpFile, SECURE_MODE);
+        }
+        catch { /* fs may not support */ }
         fs.renameSync(tmpFile, SESSIONS_STATE_FILE);
     }
     catch (err) {

package/dist/services/subagents.js

@@ -250,12 +250,30 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             ? agentConfig.workingDir || os.homedir()
             : os.homedir();
         const systemPrompt = `You are a sub-agent named "${resolvedName}". Complete the following task autonomously and report your results clearly when done. Working directory: ${effectiveCwd}`;
+        // v4.12.2 — Map the toolset preset to an explicit allowedTools list.
+        // The provider honors this override (see src/providers/claude-sdk-provider.ts
+        // line ~140). Passing undefined = full access (provider default).
+        const allowedToolsForToolset = (preset) => {
+            switch (preset) {
+                case "readonly":
+                    // Read, analyze, search — no writes, no shell, no network.
+                    return ["Read", "Glob", "Grep"];
+                case "research":
+                    // Same as readonly + web access for research tasks.
+                    return ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
+                case "full":
+                default:
+                    // undefined → provider uses its full default set.
+                    return undefined;
+            }
+        };
         for await (const chunk of registry.queryWithFallback({
             prompt: agentConfig.prompt,
             systemPrompt,
             workingDir: effectiveCwd,
             effort: "high",
             abortSignal: abort.signal,
+            allowedTools: allowedToolsForToolset(agentConfig.toolset ?? "full"),
         })) {
             if (chunk.type === "text") {
                 // Both SDK providers emit `text` as the accumulated string.
@@ -483,12 +501,12 @@ export function spawnSubAgent(agentConfig) {
     if (depth > MAX_SUBAGENT_DEPTH) {
         return Promise.reject(new Error(`Sub-agent depth limit reached (${MAX_SUBAGENT_DEPTH}). Agents can only spawn ${MAX_SUBAGENT_DEPTH} level(s) of nested agents.`));
     }
-    // G1: toolset preset. Only "full" is supported. The literal type blocks
-    // wrong values at compile time; the runtime check catches callers that
-    // bypass TypeScript (e.g. plugin code loaded at runtime).
+    // G1: toolset preset (v4.12.2 — extended with readonly + research).
+    // The literal type constrains at compile time; the runtime check catches
+    // callers that bypass TypeScript (e.g. plugin code loaded at runtime).
     const toolset = agentConfig.toolset ?? "full";
-    if (toolset !== "full") {
-        return Promise.reject(new Error(`Invalid toolset "${toolset}". Only "full" is supported in this version.`));
+    if (toolset !== "full" && toolset !== "readonly" && toolset !== "research") {
+        return Promise.reject(new Error(`Invalid toolset "${toolset}". Valid presets: full, readonly, research.`));
     }
     const maxParallel = getMaxParallelAgents();
     const queueCap = getQueueCap();

package/dist/services/timing-safe-bearer.js

@@ -0,0 +1,51 @@
+/**
+ * Timing-Safe Bearer Token Comparison (v4.12.2)
+ *
+ * Replaces naive `authHeader !== "Bearer " + token` comparison with
+ * crypto.timingSafeEqual so that token comparison time doesn't leak
+ * character-level information via side-channel.
+ *
+ * Real-world exploitability over network is low due to network jitter,
+ * but this is the right tool regardless — defense in depth.
+ *
+ * Behavior:
+ *   - Strict "Bearer <token>" format required (exactly one space)
+ *   - Empty expected token always rejects (prevents accidental auth bypass)
+ *   - Different-length tokens compared via timingSafeEqual on padded buffers
+ *     so timing doesn't leak whether the prefix matched
+ *   - Unicode-safe: Buffer.from uses UTF-8 encoding
+ */
+import { timingSafeEqual } from "crypto";
+export function timingSafeBearerMatch(authHeader, expectedToken) {
+    // Empty expected token → always reject. Prevents a misconfig where
+    // config.webhookToken is "" from accidentally allowing any "Bearer "
+    // or empty Authorization header.
+    if (!expectedToken || expectedToken.length === 0)
+        return false;
+    // Missing or non-string header
+    if (!authHeader || typeof authHeader !== "string")
+        return false;
+    // Strict format: "Bearer <token>" with exactly one space. Anything else
+    // (double space, leading whitespace, wrong prefix) is rejected. We do
+    // this via startsWith + exact-length check, not split, so attackers
+    // can't use whitespace variations to confuse the parser.
+    const prefix = "Bearer ";
+    if (!authHeader.startsWith(prefix))
+        return false;
+    const providedToken = authHeader.slice(prefix.length);
+    // timingSafeEqual requires equal-length buffers. If lengths differ,
+    // we return false — but we still touch both strings symbolically so
+    // the compare itself is constant-time relative to the shorter one.
+    // (A length leak through string.length check is acceptable; what we
+    // actually care about is that the character-by-character comparison
+    // doesn't leak.)
+    const expectedBuf = Buffer.from(expectedToken, "utf-8");
+    const providedBuf = Buffer.from(providedToken, "utf-8");
+    if (expectedBuf.length !== providedBuf.length) {
+        // Do a dummy comparison so total time is closer to constant.
+        // Not perfect but better than early-return alone.
+        timingSafeEqual(expectedBuf, expectedBuf);
+        return false;
+    }
+    return timingSafeEqual(expectedBuf, providedBuf);
+}