waha-openclaw-channel 1.16.21 → 1.17.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to the OpenClaw WAHA Plugin are documented here.
 
+## [1.17.0] - 2026-03-25 — Enterprise Hardening
+
+### Added
+- **Admin API authentication** — Bearer token auth on all `/api/admin/*` routes. Configure via `adminToken` config field or `WAHA_ADMIN_TOKEN` env var. Backward-compatible: no token = no auth.
+- **Structured JSON logging** — New `logger` module replaces all `console.log/warn/error` with machine-parseable JSON lines. Fields: `level`, `ts`, `component`, `sessionId`, `chatId`. Configurable via `logLevel` config field or `WAHA_LOG_LEVEL` env var.
+- **Prometheus metrics endpoint** — `GET /metrics` exposes heap usage, event loop lag, HTTP request rates, queue depth, API call counts, processing latency. No auth required (scraper-accessible).
+- **Config write mutex** — Promise-based mutex serializes all config file read-modify-write operations. Prevents concurrent write corruption from admin panel.
+- **Atomic config writes** — Write-to-temp-then-rename pattern prevents zero-byte config on crash.
+- **Circuit breaker** — `callWahaApi` fast-fails when session health is `unhealthy` instead of wasting 90s on retry cycles.
+- **Recovery verification** — Auto-recovery polls session status after restart, only marks success when CONNECTED (30s timeout).
+- **Graceful shutdown** — Tracks in-flight requests and waits for drain (10s timeout) before closing server.
+- **SSE connection cap** — Max 50 SSE clients; new connections beyond cap rejected with 503.
+- **Admin API rate limiting** — 60 req/min per IP sliding window on all `/api/admin/*` routes.
+- **SQLite busy_timeout** — Both DirectoryDb and AnalyticsDb set `PRAGMA busy_timeout = 5000` to handle concurrent writers.
+- **WAL checkpointing** — Periodic `PRAGMA wal_checkpoint(PASSIVE)` every 30 minutes on both databases.
+- **Media temp cleanup** — Startup sweep deletes orphaned `/tmp/openclaw/waha-media-*` files older than 10 minutes.
+- **JID path validation** — All URL path JID parameters validated against `@c.us|@g.us|@lid|@newsletter` regex.
+- **Config import validation** — Rejects unknown top-level keys beyond the known allowlist.
+- **HMAC auto-generation** — Random webhook HMAC secret generated and logged on startup when not configured. Opt-out via `webhookHmacKey: "disabled"`.
+- **Config schema bounds** — `healthCheckIntervalMs` minimum 10s, prevents flooding WAHA with health pings.
+- **Per-account rate limiting** — Each account gets its own token bucket instead of last-account-wins.
+- **RateLimiter maxQueue** — Bounded queue prevents unbounded memory growth during WAHA degradation.
+- **Timeout coverage** — All 9 bare `fetch()` calls now have `AbortSignal.timeout()`. Covers media downloads, Gemini polling, Nominatim geocoding, admin session checks.
+- **Nominatim rate limiting** — 1 req/sec enforced for geocoding calls.
+
+### Fixed
+- **Timing-safe auth** — Admin token comparison uses `crypto.timingSafeEqual` instead of `===`.
+- **Config import mutex** — Import endpoint now wrapped in `withConfigMutex` to prevent race conditions.
+- **Bare catch blocks** — 8 silent `catch {}` blocks replaced with structured `log.warn/debug` calls.
+- **Histogram double-counting** — Prometheus histogram buckets now increment only the first matching bucket.
+- **Dead metrics code** — Removed unused `apiCallsTotal`/`apiCallsSuccess` counters.
+- **InboundQueue drain safety** — `finally` block wraps recursive drain and callbacks in try/catch.
+- **SSE timer cleanup** — Keep-alive intervals `.unref()`'d and cleared on shutdown.
+- **req.url immutability** — Static file serving no longer mutates `req.url` in-place.
+- **IP source priority** — Admin rate limiter uses `remoteAddress` as primary, `X-Forwarded-For` as fallback.
+
+### New Files
+- `src/config-io.ts` — Async config I/O with mutex, atomic writes, backup rotation
+- `src/logger.ts` — Structured JSON logger with child pattern and runtime level control
+- `src/metrics.ts` — Prometheus metrics collection and `/metrics` endpoint
+
 ## [1.16.21] - 2026-03-24
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waha-openclaw-channel",
-  "version": "1.16.21",
+  "version": "1.17.0",
   "description": "OpenClaw WAHA (WhatsApp HTTP API) channel plugin",
   "type": "module",
   "main": "./index.ts",

package/src/accounts.ts

@@ -8,8 +8,11 @@ import {
 import { LRUCache } from "lru-cache";
 import { normalizeResolvedSecretInputString } from "./secret-input.js";
 import type { CoreConfig, WahaAccountConfig } from "./types.js";
+import { createLogger } from "./logger.js";
 
 
+
+const log = createLogger({ component: "accounts" });
 function normalizeOptionalAccountId(value: string | null | undefined): string | undefined {
   if (!value) return undefined;
   const trimmed = value.trim();
@@ -102,7 +105,7 @@ function resolveWahaApiKey(cfg: CoreConfig, opts: { accountId?: string }): {
         return { apiKey: fileKey, source: "secretFile" };
       }
     } catch (err) {
-      console.warn(`[waha] apiKeyFile "${merged.apiKeyFile}" unreadable: ${err}, falling back to inline apiKey`);
+      log.warn("apiKeyFile unreadable, falling back to inline apiKey", { apiKeyFile: merged.apiKeyFile, error: String(err) });
     }
   }
 

package/src/analytics.ts

@@ -2,7 +2,10 @@ import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { createLogger } from "./logger.js";
 
+
+const log = createLogger({ component: "analytics" });
 const require = createRequire(import.meta.url);
 
 export type AnalyticsEventDirection = "inbound" | "outbound";
@@ -16,15 +19,30 @@ export type AnalyticsTopChat = { chat_id: string; total: number; inbound: number
 export class AnalyticsDb {
   private db: any; // eslint-disable-line @typescript-eslint/no-explicit-any
   private _stmtInsert: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  private _walTimer: ReturnType<typeof setTimeout> | null = null;
   constructor(dbPath: string) {
     mkdirSync(join(dbPath, ".."), { recursive: true });
     const Database = require("better-sqlite3") as any; // eslint-disable-line @typescript-eslint/no-explicit-any
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("foreign_keys = ON");
+    // Phase 37 (MEM-03): Prevent SQLITE_BUSY errors under concurrent access. DO NOT REMOVE.
+    this.db.pragma("busy_timeout = 5000");
     this._createSchema();
     this._stmtInsert = this.db.prepare("INSERT INTO message_events (timestamp, direction, chat_type, action, duration_ms, status, chat_id, account_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
     this.prune(90);
+    this._startWalCheckpoint();
+  }
+  // Phase 37 (DI-01): Periodic WAL checkpoint to prevent unbounded WAL growth. DO NOT REMOVE.
+  private _startWalCheckpoint(): void {
+    const INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+    const tick = () => {
+      try { this.db.pragma("wal_checkpoint(PASSIVE)"); } catch (err) { log.warn("WAL checkpoint failed", { error: String(err) }); }
+      this._walTimer = setTimeout(tick, INTERVAL_MS);
+      this._walTimer.unref();
+    };
+    this._walTimer = setTimeout(tick, INTERVAL_MS);
+    this._walTimer.unref();
   }
   private _createSchema(): void {
     const io = "CHECK(direction IN ('inbound', 'outbound'))"; const ct = "CHECK(chat_type IN ('dm', 'group', 'channel', 'status'))"; const st = "CHECK(status IN ('success', 'error'))";
@@ -48,10 +66,14 @@ export class AnalyticsDb {
     const row = this.db.prepare("SELECT COUNT(*) AS total, SUM(CASE WHEN direction = 'inbound' THEN 1 ELSE 0 END) AS inbound, SUM(CASE WHEN direction = 'outbound' THEN 1 ELSE 0 END) AS outbound, SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) AS errors, COALESCE(AVG(CASE WHEN duration_ms IS NOT NULL THEN duration_ms END), 0) AS avg_duration_ms FROM message_events WHERE timestamp >= ? AND timestamp <= ?").get(p.startTime, p.endTime) as { total: number; inbound: number; outbound: number; errors: number; avg_duration_ms: number; };
     return { total: Number(row.total), inbound: Number(row.inbound), outbound: Number(row.outbound), errors: Number(row.errors), avg_duration_ms: Math.round(Number(row.avg_duration_ms)) };
   }
+  close(): void {
+    if (this._walTimer) { clearTimeout(this._walTimer); this._walTimer = null; }
+    this.db.close();
+  }
   prune(maxAgeDays: number): void {
     const cutoff = Date.now() - maxAgeDays * 86400000;
     const r = this.db.prepare("DELETE FROM message_events WHERE timestamp < ?").run(cutoff) as { changes: number };
-    if (r.changes > 0) console.log("[waha] analytics: pruned " + r.changes + " events older than " + maxAgeDays + " days");
+    if (r.changes > 0) log.info("analytics: pruned " + r.changes + " events older than " + maxAgeDays + " days");
   }
 }
 let _analyticsDb: AnalyticsDb | null = null;

package/src/auto-reply.ts

@@ -17,7 +17,10 @@
 import { getDirectoryDb } from "./directory.js";
 import { sendWahaText } from "./send.js";
 import type { CoreConfig } from "./types.js";
+import { createLogger } from "./logger.js";
 
+
+const log = createLogger({ component: "auto-reply" });
 // ── AutoReplyEngine ───────────────────────────────────────────────────────────
 
 export class AutoReplyEngine {
@@ -78,7 +81,7 @@ export class AutoReplyEngine {
     } catch (err) {
       // Log but don't throw — rejection send failure is non-fatal.
       // The contact simply won't receive a rejection message.
-      console.warn(`[waha] auto-reply send failed for ${jid}: ${String(err)}`);
+      log.warn("auto-reply send failed", { jid, error: String(err) });
       return;
     }
 

package/src/channel.ts

@@ -91,7 +91,10 @@ import { getRulesBasePath } from "./identity-resolver.js";
 import { getDirectoryDb } from "./directory.js";
 // Phase 30, Plan 01: Analytics instrumentation. DO NOT REMOVE.
 import { recordAnalyticsEvent } from "./analytics.js";
+import { createLogger } from "./logger.js";
 
+
+const log = createLogger({ component: "channel" });
 // Cached config for outbound adapter — handleAction receives cfg as a param
 // and caches it here so outbound methods (sendText, sendMedia, sendPoll) can
 // access config without calling readConfigFile() which may crash.
@@ -535,7 +538,7 @@ export async function checkGroupMembership(
       (err instanceof Error && "status" in err && (err as any).status === 404) ||
       /not found|404|does not exist/i.test(msg);
     if (isNotFound) {
-      console.warn(`[waha] checkGroupMembership: session=${session} not in group=${groupId}`);
+      log.warn("checkGroupMembership: session not in group", { session, groupId });
       return false;
     }
     throw err;
@@ -578,7 +581,7 @@ const wahaMessageActions: ChannelMessageActionAdapter = {
         const _chatId = typeof p.chatId === "string" ? p.chatId : (typeof p.to === "string" ? p.to : undefined);
         const _chatType = _chatId?.endsWith("@g.us") ? "group" : (_chatId?.endsWith("@newsletter") ? "channel" : "dm");
         recordAnalyticsEvent({ direction: "outbound", chat_type: _chatType, action, duration_ms: Date.now() - _analyticsStart, status: "success", chat_id: _chatId, account_id: aid });
-      } catch (analyticsErr) { console.warn("[waha] analytics recording failed:", analyticsErr instanceof Error ? analyticsErr.message : String(analyticsErr)); }
+      } catch (analyticsErr) { log.warn("analytics recording failed", { error: analyticsErr instanceof Error ? analyticsErr.message : String(analyticsErr) }); }
       return actionResult;
     };
 
@@ -661,9 +664,9 @@ const wahaMessageActions: ChannelMessageActionAdapter = {
         } catch (routeErr) {
           const msg = routeErr instanceof Error ? routeErr.message : String(routeErr);
           if (/No full-access sessions|No session is a member/i.test(msg)) {
-            console.warn(`[waha] cross-session routing — no reachable session for ${chatId}, using default account`);
+            log.warn("cross-session routing — no reachable session, using default account", { chatId });
           } else {
-            console.error(`[waha] cross-session routing unexpected error for ${chatId}: ${msg}`);
+            log.error("cross-session routing unexpected error", { chatId, error: msg });
           }
         }
       }
@@ -776,7 +779,7 @@ const wahaMessageActions: ChannelMessageActionAdapter = {
         const _chatId = typeof p.chatId === "string" ? p.chatId : (typeof p.to === "string" ? p.to : undefined);
         const _chatType = _chatId?.endsWith("@g.us") ? "group" : (_chatId?.endsWith("@newsletter") ? "channel" : "dm");
         recordAnalyticsEvent({ direction: "outbound", chat_type: _chatType, action, duration_ms: Date.now() - _analyticsStart, status: "error", chat_id: _chatId, account_id: aid });
-      } catch (analyticsErr) { console.warn("[waha] analytics recording failed:", analyticsErr instanceof Error ? analyticsErr.message : String(analyticsErr)); }
+      } catch (analyticsErr) { log.warn("analytics recording failed", { error: analyticsErr instanceof Error ? analyticsErr.message : String(analyticsErr) }); }
 
       return {
         content: [{ type: "text" as const, text: formatActionError(err, { action, target }) }],
@@ -800,7 +803,7 @@ export const wahaPlugin: ChannelPlugin<ResolvedWahaAccount> = {
     idLabel: "whatsappUserId",
     normalizeAllowEntry: (entry) => normalizeWahaAllowEntry(entry),
     notifyApproval: async ({ id }) => {
-      console.log(`[waha] user ${id} approved for pairing`);
+      log.info(`user ${id} approved for pairing`);
     },
   },
   capabilities: {
@@ -1035,7 +1038,9 @@ export const wahaPlugin: ChannelPlugin<ResolvedWahaAccount> = {
       // Wire reliability config from plugin settings to http-client module.
       // DO NOT REMOVE — configureReliability() sets timeout and rate limiter defaults.
       // Added Phase 1 gap closure (2026-03-11).
+      // Phase 40 (CFG-02): pass accountId for per-account rate limiting. DO NOT CHANGE.
       configureReliability({
+        accountId: account.accountId,
         timeoutMs: account.config.timeoutMs,
         capacity: account.config.rateLimitCapacity,
         refillRate: account.config.rateLimitRefillRate,

package/src/config-io.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock node:fs/promises before importing module
+vi.mock("node:fs/promises", () => ({
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  rename: vi.fn(),
+  copyFile: vi.fn(),
+  stat: vi.fn(),
+  unlink: vi.fn(),
+}));
+
+// Mock node:os to control homedir
+vi.mock("node:os", () => ({
+  homedir: vi.fn(() => "/home/testuser"),
+}));
+
+import { readFile, writeFile, rename, copyFile, stat } from "node:fs/promises";
+import { readConfig, writeConfig, modifyConfig, withConfigMutex, getConfigPath } from "./config-io.js";
+
+const mockReadFile = vi.mocked(readFile);
+const mockWriteFile = vi.mocked(writeFile);
+const mockRename = vi.mocked(rename);
+const mockCopyFile = vi.mocked(copyFile);
+const mockStat = vi.mocked(stat);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("config-io", () => {
+  describe("getConfigPath", () => {
+    it("returns default path when no env var set", () => {
+      delete process.env.OPENCLAW_CONFIG_PATH;
+      const p = getConfigPath();
+      expect(p).toContain(".openclaw");
+      expect(p).toContain("openclaw.json");
+    });
+
+    it("respects OPENCLAW_CONFIG_PATH env var", () => {
+      process.env.OPENCLAW_CONFIG_PATH = "/custom/config.json";
+      expect(getConfigPath()).toBe("/custom/config.json");
+      delete process.env.OPENCLAW_CONFIG_PATH;
+    });
+  });
+
+  describe("readConfig", () => {
+    it("Test 1: returns parsed JSON object from file", async () => {
+      const data = { channels: { waha: { foo: "bar" } } };
+      mockReadFile.mockResolvedValue(JSON.stringify(data));
+      const result = await readConfig("/tmp/config.json");
+      expect(result).toEqual(data);
+      expect(mockReadFile).toHaveBeenCalledWith("/tmp/config.json", "utf-8");
+    });
+
+    it("Test 2: throws on missing file", async () => {
+      mockReadFile.mockRejectedValue(new Error("ENOENT: no such file"));
+      await expect(readConfig("/tmp/missing.json")).rejects.toThrow("ENOENT");
+    });
+  });
+
+  describe("writeConfig", () => {
+    it("Test 3: writes JSON to .tmp file then renames to target", async () => {
+      // stat rejects (no existing file to backup)
+      mockStat.mockRejectedValue(new Error("ENOENT"));
+      mockWriteFile.mockResolvedValue(undefined);
+      mockRename.mockResolvedValue(undefined);
+
+      const data = { channels: { waha: {} } };
+      await writeConfig("/tmp/config.json", data);
+
+      // Should write to .tmp first
+      expect(mockWriteFile).toHaveBeenCalledWith(
+        "/tmp/config.json.tmp",
+        JSON.stringify(data, null, 2),
+        "utf-8"
+      );
+      // Then rename .tmp -> target
+      expect(mockRename).toHaveBeenCalledWith(
+        "/tmp/config.json.tmp",
+        "/tmp/config.json"
+      );
+    });
+
+    it("Test 4: creates 3 rolling backups before writing", async () => {
+      // All backup files exist
+      mockStat.mockResolvedValue({ isFile: () => true } as any);
+      mockRename.mockResolvedValue(undefined);
+      mockCopyFile.mockResolvedValue(undefined);
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await writeConfig("/tmp/config.json", { x: 1 });
+
+      // Should rotate: .bak.2 -> .bak.3, .bak.1 -> .bak.2
+      const renameCalls = mockRename.mock.calls;
+      expect(renameCalls).toContainEqual(["/tmp/config.json.bak.2", "/tmp/config.json.bak.3"]);
+      expect(renameCalls).toContainEqual(["/tmp/config.json.bak.1", "/tmp/config.json.bak.2"]);
+      // Should copy current -> .bak.1
+      expect(mockCopyFile).toHaveBeenCalledWith("/tmp/config.json", "/tmp/config.json.bak.1");
+    });
+  });
+
+  describe("withConfigMutex", () => {
+    it("Test 5: serializes concurrent calls", async () => {
+      const order: number[] = [];
+      let resolveFirst: () => void;
+      const firstBlocks = new Promise<void>((r) => { resolveFirst = r; });
+
+      const call1 = withConfigMutex(async () => {
+        order.push(1);
+        await firstBlocks;
+        order.push(2);
+      });
+
+      const call2 = withConfigMutex(async () => {
+        order.push(3);
+      });
+
+      // Let first call complete
+      resolveFirst!();
+      await call1;
+      await call2;
+
+      // call2 (push 3) should happen AFTER call1 finishes (push 2)
+      expect(order).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe("modifyConfig", () => {
+    it("Test 6: does atomic read-modify-write under mutex", async () => {
+      const original = { channels: { waha: { count: 0 } } };
+      mockReadFile.mockResolvedValue(JSON.stringify(original));
+      mockStat.mockRejectedValue(new Error("ENOENT"));
+      mockWriteFile.mockResolvedValue(undefined);
+      mockRename.mockResolvedValue(undefined);
+
+      await modifyConfig("/tmp/config.json", (config) => {
+        (config as any).channels.waha.count = 42;
+      });
+
+      // Should have written the modified config
+      const writtenData = JSON.parse(mockWriteFile.mock.calls[0][1] as string);
+      expect(writtenData.channels.waha.count).toBe(42);
+    });
+
+    it("Test 6b: modifyConfig uses return value if fn returns an object", async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ old: true }));
+      mockStat.mockRejectedValue(new Error("ENOENT"));
+      mockWriteFile.mockResolvedValue(undefined);
+      mockRename.mockResolvedValue(undefined);
+
+      await modifyConfig("/tmp/config.json", () => {
+        return { new: true };
+      });
+
+      const writtenData = JSON.parse(mockWriteFile.mock.calls[0][1] as string);
+      expect(writtenData).toEqual({ new: true });
+    });
+  });
+
+  describe("atomic write safety", () => {
+    it("Test 7: original file intact if writeFile crashes", async () => {
+      mockStat.mockRejectedValue(new Error("ENOENT"));
+      mockWriteFile.mockRejectedValue(new Error("disk full"));
+
+      await expect(writeConfig("/tmp/config.json", { x: 1 })).rejects.toThrow("disk full");
+
+      // rename should NOT have been called (write failed before rename)
+      const renameCallsForFinal = mockRename.mock.calls.filter(
+        (c) => c[0] === "/tmp/config.json.tmp" && c[1] === "/tmp/config.json"
+      );
+      expect(renameCallsForFinal).toHaveLength(0);
+    });
+  });
+});

package/src/config-io.ts

@@ -0,0 +1,151 @@
+/**
+ * config-io.ts — Centralized config I/O module with safety guarantees.
+ *
+ * Provides:
+ * - Async file operations (node:fs/promises, never sync)
+ * - Promise-based mutex serializing all config writes (CON-01)
+ * - Atomic write-to-temp-then-rename so crash mid-write leaves previous valid file (DI-02)
+ * - Rolling backup rotation (3 backups) before each write
+ *
+ * Added Phase 33 (config-infrastructure). DO NOT CHANGE without reading all comments.
+ */
+
+import { readFile, writeFile, rename, copyFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createLogger } from "./logger.js";
+
+
+const log = createLogger({ component: "config-io" });
+// ──────────────────────────────────────────────────────────────────────────────
+// Config path
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the path to the OpenClaw config file.
+ * Respects OPENCLAW_CONFIG_PATH env var, defaults to ~/.openclaw/openclaw.json.
+ * Config save path: must write to ~/.openclaw/openclaw.json (NOT workspace subfolder).
+ * DO NOT CHANGE — matches monitor.ts getConfigPath behavior.
+ */
+export function getConfigPath(): string {
+  return process.env.OPENCLAW_CONFIG_PATH ?? join(homedir(), ".openclaw", "openclaw.json");
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Promise-based mutex (CON-01)
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Simple promise-chain mutex that serializes all config writes.
+ * Prevents concurrent read-modify-write races on openclaw.json.
+ * DO NOT CHANGE — concurrent config writes depend on this serialization.
+ */
+let configMutexChain = Promise.resolve();
+
+export function withConfigMutex<T>(fn: () => Promise<T>): Promise<T> {
+  const result = configMutexChain.then(fn, fn);
+  configMutexChain = result.then(
+    () => {},
+    () => {}
+  );
+  return result;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Read config (MEM-01 — async I/O)
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Reads and parses the OpenClaw config file.
+ * Uses async fs/promises — never readFileSync.
+ * Throws on missing file or invalid JSON.
+ */
+export async function readConfig(configPath: string): Promise<Record<string, unknown>> {
+  const raw = await readFile(configPath, "utf-8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Backup rotation
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Async version of rotateConfigBackups from monitor.ts.
+ * Creates rolling backups: .bak.1 (newest), .bak.2, .bak.3 (oldest).
+ * Rotation: delete .bak.3 (overwritten by rename), shift .bak.2->.bak.3, .bak.1->.bak.2, copy current->.bak.1.
+ * Failure is non-fatal: logs a warning but does NOT block the save.
+ * Added Phase 33. DO NOT REMOVE.
+ */
+async function rotateConfigBackups(configPath: string): Promise<void> {
+  try {
+    const bak1 = configPath + ".bak.1";
+    const bak2 = configPath + ".bak.2";
+    const bak3 = configPath + ".bak.3";
+
+    // Check which files exist using async stat
+    const exists = async (p: string): Promise<boolean> => {
+      try {
+        await stat(p);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+    // Shift existing backups: .bak.2 -> .bak.3, .bak.1 -> .bak.2
+    if (await exists(bak2)) await rename(bak2, bak3);
+    if (await exists(bak1)) await rename(bak1, bak2);
+    // Copy current config as newest backup
+    if (await exists(configPath)) await copyFile(configPath, bak1);
+  } catch (err) {
+    log.warn("rotateConfigBackups: backup failed (non-fatal)", { error: String(err) });
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Write config (DI-02 — atomic write-to-temp-then-rename)
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Atomically writes config to disk.
+ * 1. Rotates backups (non-fatal if rotation fails)
+ * 2. Writes to configPath.tmp
+ * 3. Renames .tmp -> configPath (atomic on most filesystems)
+ *
+ * If crash/error occurs during writeFile, the original config file is untouched.
+ * Uses async fs/promises — never writeFileSync.
+ * DO NOT CHANGE — atomic write pattern prevents data loss on crash.
+ */
+export async function writeConfig(configPath: string, config: Record<string, unknown>): Promise<void> {
+  await rotateConfigBackups(configPath);
+  const tmpPath = configPath + ".tmp";
+  await writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+  await rename(tmpPath, configPath);
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Modify config (convenience wrapper)
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Atomic read-modify-write under mutex.
+ * 1. Acquires config mutex (serializes with all other config writes)
+ * 2. Reads current config
+ * 3. Calls fn(config) — if fn returns a new object, uses that; if void, uses mutated original
+ * 4. Writes result atomically
+ *
+ * Usage:
+ *   await modifyConfig(path, (cfg) => { cfg.channels.waha.foo = 'bar'; });
+ *   await modifyConfig(path, (cfg) => ({ ...cfg, newKey: 'val' }));
+ */
+export async function modifyConfig(
+  configPath: string,
+  fn: (config: Record<string, unknown>) => Record<string, unknown> | void
+): Promise<void> {
+  return withConfigMutex(async () => {
+    const config = await readConfig(configPath);
+    const result = fn(config);
+    const toWrite = result !== undefined && result !== null ? result : config;
+    await writeConfig(configPath, toWrite);
+  });
+}

package/src/config-schema.ts

@@ -96,7 +96,8 @@ export const WahaAccountSchemaBase = z
     rateLimitRefillRate: z.number().positive().optional().default(15),
     // Phase 2 config — health monitoring and inbound queue sizing.
     // Added in Phase 2, Plan 01 (2026-03-11). DO NOT REMOVE.
-    healthCheckIntervalMs: z.number().int().positive().optional().default(60_000),
+    // Phase 40 (CFG-01): .min(10000) prevents dangerously fast health checks. DO NOT REMOVE.
+    healthCheckIntervalMs: z.number().int().positive().min(10_000).optional().default(60_000),
     dmQueueSize: z.number().int().positive().optional().default(50),
     groupQueueSize: z.number().int().positive().optional().default(50),
     // Phase 3 config — auto link preview in sendWahaText.
@@ -146,6 +147,11 @@ export const WahaAccountSchemaBase = z
       ),
     }).optional().default({}),
 
+    // Phase 35 (OBS-01): Structured log level. Overrides WAHA_LOG_LEVEL env var.
+    // Accepted values: "debug", "info", "warn", "error". Default: "info".
+    // DO NOT REMOVE — used by logger.ts to configure runtime log verbosity.
+    logLevel: z.enum(["debug", "info", "warn", "error"]).optional(),
+
     autoReply: z.object({
       enabled: z.boolean().optional().default(false),
       message: z.string().optional().default(
@@ -170,6 +176,11 @@ export const WahaAccountSchema = WahaAccountSchemaBase.superRefine((value, ctx)
 export const WahaConfigSchema = WahaAccountSchemaBase.extend({
   accounts: z.record(z.string(), WahaAccountSchema.optional()).optional(),
   defaultAccount: z.string().optional(),
+  // Phase 34 (SEC-01): Bearer token for admin API authentication.
+  // When set, all /api/admin/* routes require Authorization: Bearer <token>.
+  // Also supports WAHA_ADMIN_TOKEN env var. When neither is set, no auth required (backward compat).
+  // DO NOT REMOVE — removing this disables admin panel authentication.
+  adminToken: z.string().optional(),
 }).superRefine((value, ctx) => {
   requireOpenAllowFrom({
     policy: value.dmPolicy,
@@ -201,7 +212,7 @@ export type ConfigValidationResult =
 export function validateWahaConfig(value: unknown): ConfigValidationResult {
   // WahaConfigSchema is WahaAccountSchemaBase.extend({accounts,defaultAccount}).superRefine(...)
   // .superRefine() returns ZodEffects which has no .shape — derive keys from the base + extension.
-  const knownKeys = new Set([...Object.keys(WahaAccountSchemaBase.shape), 'accounts', 'defaultAccount']);
+  const knownKeys = new Set([...Object.keys(WahaAccountSchemaBase.shape), 'accounts', 'defaultAccount', 'adminToken']);
   const stripped = typeof value === 'object' && value !== null
     ? Object.fromEntries(Object.entries(value).filter(([k]) => knownKeys.has(k)))
     : value;