@manybot/manybot 5.8.0 → 5.9.1

package/dist/kernel/chatOverrides.test.js

@@ -0,0 +1,59 @@
+import test, { describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { getChatPrefix, getChatLocale } from "#kernel/chatOverrides.js";
+import { buildSettingsApi } from "#kernel/settingsDb.js";
+import { CMD_PREFIX } from "#config";
+describe("kernel/chatOverrides", () => {
+    // Already in normalized form ("@c.us") so writes and reads use the
+    // exact same storage key without relying on normalizeJid to no-op.
+    const chatId = "5511977776666@c.us";
+    beforeEach(() => {
+        buildSettingsApi("core", chatId).deleteAll();
+    });
+    afterEach(() => {
+        buildSettingsApi("core", chatId).deleteAll();
+    });
+    describe("getChatPrefix", () => {
+        test("returns the global CMD_PREFIX when no override is set", () => {
+            assert.equal(getChatPrefix(chatId), CMD_PREFIX);
+        });
+        test("returns the chat's saved override once !config prefixo has set one", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "#");
+            assert.equal(getChatPrefix(chatId), "#");
+        });
+        test("does not leak one chat's override into another chat", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "#");
+            assert.equal(getChatPrefix("5511900000000@c.us"), CMD_PREFIX);
+        });
+        test("reads back a value written under the raw (non-normalized) wire jid form", () => {
+            // buildApi()/buildMessageContext() scope ctx.settings with
+            // normalizeJid(msg.chatId) — a raw "@s.whatsapp.net" jid (with a
+            // device suffix, as WhatsApp sends it) must normalize to the same
+            // key so a write from the live message path is visible here too.
+            const rawJid = "5511977776666:12@s.whatsapp.net";
+            buildSettingsApi("core", "5511977776666@c.us").set("chat_prefix", "$");
+            assert.equal(getChatPrefix(rawJid), "$");
+        });
+        test("falls back to the global prefix for a blank saved override", () => {
+            buildSettingsApi("core", chatId).set("chat_prefix", "");
+            assert.equal(getChatPrefix(chatId), CMD_PREFIX);
+        });
+    });
+    describe("getChatLocale", () => {
+        test("returns undefined when no override is set, so callers fall back to the global language", () => {
+            assert.equal(getChatLocale(chatId), undefined);
+        });
+        test("returns the chat's saved override once !config idioma has set one", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "es");
+            assert.equal(getChatLocale(chatId), "es");
+        });
+        test("does not leak one chat's override into another chat", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "es");
+            assert.equal(getChatLocale("5511900000000@c.us"), undefined);
+        });
+        test("falls back to undefined for a blank saved override", () => {
+            buildSettingsApi("core", chatId).set("chat_locale", "");
+            assert.equal(getChatLocale(chatId), undefined);
+        });
+    });
+});

package/dist/kernel/commandAccess.test.js

@@ -1,7 +1,7 @@
 import test, { describe } from "node:test";
 import assert from "node:assert/strict";
 import { exists, desc, manual, list, isMenuAlias } from "#kernel/commandAccess.js";
-import { buildCommandRegistry } from "#kernel/commandRegistry.js";
+import { buildCommandRegistry, DEFAULT_MENU_CONFIG } from "#kernel/commandRegistry.js";
 function createTestRegistry() {
     const plugins = new Map([
         [
@@ -31,7 +31,7 @@ function createTestRegistry() {
     const categories = {
         utils: { label: { pt: "Utilitários", en: "Utilities" }, order: 1 },
     };
-    return buildCommandRegistry(null, plugins, undefined, undefined, categories);
+    return buildCommandRegistry(null, plugins, undefined, { ...DEFAULT_MENU_CONFIG, enabled: true }, categories);
 }
 describe("kernel/commandAccess", () => {
     test("exists() is true for cmd and alias, false for unknown", () => {

package/dist/kernel/commandDeprecation.js

@@ -101,7 +101,8 @@ export function syncCommandHistory(byId, defaults, specs) {
             logger.warn(t("system.commandDeprecationRenamed", {
                 id,
                 old: prevCmd,
-                new: entry.cmd
+                new: entry.cmd,
+                days: String(defaults.notifyPeriodDays)
             }));
         }
         stmts.insertHistory.run(id, entry.cmd);
@@ -121,7 +122,8 @@ export function syncCommandHistory(byId, defaults, specs) {
             stmts.upsertDeprecation.run(existing.cmd, id, null, now + periodMs, spec?.deprecatedMessage ?? null);
             logger.warn(t("system.commandDeprecationRemoved", {
                 id,
-                old: existing.cmd
+                old: existing.cmd,
+                days: String(defaults.notifyPeriodDays)
             }));
         }
         stmts.deleteHistory.run(id);

package/dist/kernel/commandDeprecation.test.js

@@ -13,6 +13,8 @@ function createMockEntry(id, cmd) {
         source: "plugin",
         pluginName: "testPlugin",
         function: null,
+        functions: [],
+        loading: null,
         handler: null,
         text: null,
         permissions: {
@@ -23,11 +25,15 @@ function createMockEntry(id, cmd) {
             cooldownSeconds: 0,
             whitelist: null,
             blacklist: null,
+            dono: null,
+            allowedChats: null,
+            hiddenOutsideScope: null,
             messages: {},
         },
         arguments: [],
         subcommands: {},
         categoryHiddenInScope: null,
+        hiddenOutsideScope: null,
     };
 }
 describe("kernel/commandDeprecation", () => {
@@ -81,7 +87,8 @@ describe("kernel/commandDeprecation", () => {
         const specs1 = [{
                 id: "plugin::optOut",
                 plugin: "plugin",
-                function: "optOut",
+                functions: ["optOut"],
+                loading: null,
                 cmd: "alpha",
                 aliases: [],
                 desc: null,

package/dist/kernel/commandMenu.js

@@ -6,13 +6,54 @@
 import { CMD_PREFIX } from "#config";
 import { getCurrentLang, tFor } from "#i18n";
 import { buildSettingsApi } from "./settingsDb.js";
+/** Maximum age (ms) of an incoming message for the welcome to fire.
+ *  Matches `MAX_MESSAGE_AGE_SECONDS` in `drivers/baileys/index.ts` so the
+ *  welcome can never fire on a message the driver would have dropped as
+ *  stale. See `checkAndTriggerWelcomeMessage` for the full rationale. */
+const MAX_WELCOME_AGE_MS = 60 * 1000;
 /**
  * Checks if the user should be shown the welcome message,
  * and marks them as seen if so.
+ *
+ * Two extra gates protect against the "ghost welcome" failure mode where
+ * a welcome fires out of the blue for a sender the bot never heard from:
+ *
+ *   - The incoming message must have non-empty text. Baileys 7.x has a
+ *     documented offline-flush bug where, after a reconnect, the
+ *     event-buffer can reclassify receipts as `messages.upsert` events
+ *     (the buffer interleaves message and receipt frames during the
+ *     replay window). Those events arrive with `fromMe=false`, in a
+ *     real DM, with `body` empty — every other condition for a welcome
+ *     fires, but they aren't real messages. Requiring a non-empty body
+ *     filters this entire class of synthetic upserts.
+ *
+ *   - The incoming message's `timestamp` must be within
+ *     `MAX_WELCOME_AGE_MS` of `now`. The Baileys 7.x line also has
+ *     widely-reported cases where the event-buffer delivers
+ *     `messages.upsert` events minutes, hours, or even days after they
+ *     originally occurred (they sit in the buffer during a long
+ *     disconnect and are drained in order on reconnect). A sender
+ *     whose first-ever contact with the bot was days ago is not a
+ *     "first-time" sender in any meaningful sense — the welcome is for
+ *     a real, live first contact, not a delayed replay. This mirrors
+ *     `isMessageStale()` in `drivers/baileys/index.ts` (60s), which
+ *     is the same threshold the driver itself uses to drop stale
+ *     events before they reach the handler. We keep the threshold the
+ *     same here so the two stay in sync: if the driver decided the
+ *     message is "real-time enough" to dispatch, the welcome fires;
+ *     if the driver would have dropped it, we never reach this path.
  */
-export function checkAndTriggerWelcomeMessage(userId, registry, lang) {
+export function checkAndTriggerWelcomeMessage(userId, registry, msg, lang, prefix = CMD_PREFIX) {
     if (!registry.menu.welcomeMessage)
         return null;
+    if (!msg || !msg.body || msg.body.trim() === "")
+        return null;
+    const msgTsMs = msg.timestamp ?? 0;
+    if (msgTsMs > 0) {
+        const ageMs = Date.now() - msgTsMs;
+        if (ageMs > MAX_WELCOME_AGE_MS)
+            return null;
+    }
     const settings = buildSettingsApi("kernel", userId);
     const lastSeen = settings.get("last_welcome_seen");
     const now = Math.floor(Date.now() / 1000);
@@ -22,7 +63,7 @@ export function checkAndTriggerWelcomeMessage(userId, registry, lang) {
         const rawMsg = resolveLocalizedString(registry.menu.welcomeMessage, lang);
         if (!rawMsg)
             return null;
-        return rawMsg.replace(/\{prefix\}/g, CMD_PREFIX);
+        return rawMsg.replace(/\{prefix\}/g, prefix);
     }
     return null;
 }
@@ -79,6 +120,8 @@ export function renderOverview(registry, lang, page, scope) {
                     return true;
                 if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
                     return false;
+                if (e.hiddenOutsideScope && e.hiddenOutsideScope !== "any" && e.hiddenOutsideScope !== scope)
+                    return false;
                 return true;
             })
                 .sort((a, b) => a.cmd.localeCompare(b.cmd));
@@ -106,6 +149,8 @@ export function renderOverview(registry, lang, page, scope) {
                 return true;
             if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
                 return false;
+            if (e.hiddenOutsideScope && e.hiddenOutsideScope !== "any" && e.hiddenOutsideScope !== scope)
+                return false;
             return true;
         })
             .sort((a, b) => a.cmd.localeCompare(b.cmd));
@@ -131,6 +176,8 @@ export function renderOverview(registry, lang, page, scope) {
                 return true;
             if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
                 return false;
+            if (e.hiddenOutsideScope && e.hiddenOutsideScope !== "any" && e.hiddenOutsideScope !== scope)
+                return false;
             return true;
         });
         const startIdx = page ? (page - 1) * pageSize : 0;
@@ -191,6 +238,8 @@ export function renderCategory(registry, categoryKey, lang, scope) {
         // If entry has a specific scope defined and it doesn't match the requested scope, exclude it
         if (e.categoryHiddenInScope && e.categoryHiddenInScope === scope)
             return false;
+        if (e.hiddenOutsideScope && e.hiddenOutsideScope !== "any" && e.hiddenOutsideScope !== scope)
+            return false;
         return true;
     })
         .sort((a, b) => a.cmd.localeCompare(b.cmd));
@@ -235,8 +284,48 @@ export function renderManual(entry, registry, lang) {
     }
     return parts.join("\n").trim();
 }
+function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/** Closest known cmd/alias to `invocation` within `maxDistance`, or null. */
+function findClosestInvocation(invocation, registry, maxDistance) {
+    let best = null;
+    let bestDist = Infinity;
+    for (const known of registry.byInvocation.keys()) {
+        const dist = levenshtein(invocation, known);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = known;
+        }
+    }
+    return best !== null && bestDist > 0 && bestDist <= maxDistance ? best : null;
+}
 export function renderNotFound(invocation, registry, lang) {
     const menuCmd = registry.menu.cmd;
+    if (registry.menu.suggestSimilar) {
+        const suggestion = findClosestInvocation(invocation, registry, registry.menu.suggestMaxDistance);
+        if (suggestion) {
+            return tFor(lang, "system.commandNotFoundSuggestion", {
+                cmd: invocation,
+                suggestion,
+                prefix: CMD_PREFIX,
+                menuCmd
+            });
+        }
+    }
     return tFor(lang, "system.commandNotFound", { cmd: invocation, prefix: CMD_PREFIX, menuCmd });
 }
 export function handleMenuCommand(command, rawArgs, registry, lang, scope) {

package/dist/kernel/commandMenu.test.js

@@ -46,6 +46,8 @@ function createTestRegistry() {
         cmd: "help",
         aliases: ["help", "menu"],
         notFoundFallback: false,
+        suggestSimilar: false,
+        suggestMaxDistance: 2,
         welcomeMessage: { pt: "Bem-vindo ao bot! Use {prefix}help para o menu.", en: "Welcome! Use {prefix}help." },
         welcomeWindowDays: 3,
         pageSize: 2,
@@ -115,6 +117,8 @@ describe("kernel/commandMenu", () => {
                 cmd: "help",
                 aliases: ["help"],
                 notFoundFallback: false,
+                suggestSimilar: false,
+                suggestMaxDistance: 2,
                 welcomeMessage: null,
                 welcomeWindowDays: 3,
                 pageSize: 2,
@@ -192,6 +196,8 @@ describe("kernel/commandMenu", () => {
                 cmd: "help",
                 aliases: ["help"],
                 notFoundFallback: false,
+                suggestSimilar: false,
+                suggestMaxDistance: 2,
                 welcomeMessage: null,
                 welcomeWindowDays: 3,
                 pageSize: 1,
@@ -223,12 +229,135 @@ describe("kernel/commandMenu", () => {
             const userId = "test_user_welcome_1";
             const settings = buildSettingsApi("kernel", userId);
             settings.delete("last_welcome_seen");
-            const msg = checkAndTriggerWelcomeMessage(userId, registry, "pt");
+            const msg = checkAndTriggerWelcomeMessage(userId, registry, { body: "oi", timestamp: Date.now() }, "pt");
             assert.ok(msg);
             assert.match(msg, /Bem-vindo ao bot! Use !help para o menu\./);
             // Immediately checking again returns null
-            const secondCheck = checkAndTriggerWelcomeMessage(userId, registry, "pt");
+            const secondCheck = checkAndTriggerWelcomeMessage(userId, registry, { body: "oi", timestamp: Date.now() }, "pt");
             assert.equal(secondCheck, null);
         });
+        test("does not fire when the incoming message has no body (offline-flush receipt misclassification)", () => {
+            const registry = createTestRegistry();
+            const userId = "test_user_welcome_empty_body";
+            buildSettingsApi("kernel", userId).delete("last_welcome_seen");
+            const msg = checkAndTriggerWelcomeMessage(userId, registry, { body: "", timestamp: Date.now() });
+            assert.equal(msg, null, "no welcome for a body-less message");
+            const msg2 = checkAndTriggerWelcomeMessage(userId, registry, { body: "   ", timestamp: Date.now() });
+            assert.equal(msg2, null, "no welcome for a whitespace-only body either");
+        });
+        test("does not fire when the incoming message is older than the freshness window (offline-flush delayed replay)", () => {
+            const registry = createTestRegistry();
+            const userId = "test_user_welcome_stale_replay";
+            buildSettingsApi("kernel", userId).delete("last_welcome_seen");
+            const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
+            const msg = checkAndTriggerWelcomeMessage(userId, registry, { body: "oi", timestamp: twoHoursAgo });
+            assert.equal(msg, null, "no welcome for a 2-hour-old replay");
+        });
+        test("does fire for a fresh in-window message (control case for the new gates)", () => {
+            const registry = createTestRegistry();
+            const userId = "test_user_welcome_fresh";
+            buildSettingsApi("kernel", userId).delete("last_welcome_seen");
+            const msg = checkAndTriggerWelcomeMessage(userId, registry, { body: "oi", timestamp: Date.now() });
+            assert.ok(msg, "welcome fires for a current, non-empty message");
+        });
+        test("does not fire when the msg envelope is missing (defensive — caller must always pass one)", () => {
+            const registry = createTestRegistry();
+            const userId = "test_user_welcome_no_envelope";
+            buildSettingsApi("kernel", userId).delete("last_welcome_seen");
+            const msg = checkAndTriggerWelcomeMessage(userId, registry);
+            assert.equal(msg, null);
+        });
+        test("uses the prefix override in the {prefix} placeholder instead of the global default", () => {
+            const registry = createTestRegistry();
+            const userId = "test_user_welcome_custom_prefix";
+            buildSettingsApi("kernel", userId).delete("last_welcome_seen");
+            const msg = checkAndTriggerWelcomeMessage(userId, registry, { body: "oi", timestamp: Date.now() }, "pt", "#");
+            assert.ok(msg);
+            assert.match(msg, /Use #help para o menu\./);
+        });
+    });
+    describe("hiddenOutsideScope (group/dm suppression)", () => {
+        function buildScopeRegistry() {
+            const noop = async () => { };
+            const plugins = new Map([
+                [
+                    "scopePlugin",
+                    {
+                        name: "scopePlugin",
+                        status: "active",
+                        manifest: { name: "scopePlugin", version: "1.0.0" },
+                        commands: {
+                            groupOnlyFn: {
+                                cmd: "g",
+                                aliases: [],
+                                desc: "Group-only command",
+                                category: "utils",
+                                permissions: { groupOnly: true },
+                                handler: noop,
+                            },
+                            dmOnlyFn: {
+                                cmd: "d",
+                                aliases: [],
+                                desc: "DM-only command",
+                                category: "utils",
+                                permissions: { dmOnly: true },
+                                handler: noop,
+                            },
+                            bothFn: {
+                                cmd: "b",
+                                aliases: [],
+                                desc: "Both-scopes command",
+                                category: "utils",
+                                handler: noop,
+                            },
+                        },
+                    },
+                ],
+            ]);
+            const menu = {
+                title: "Scope",
+                intro: null,
+                footer: null,
+                cmd: "help",
+                aliases: ["help"],
+                notFoundFallback: false,
+                suggestSimilar: false,
+                suggestMaxDistance: 2,
+                welcomeMessage: null,
+                welcomeWindowDays: 3,
+                pageSize: 10,
+            };
+            return buildCommandRegistry(null, plugins, undefined, menu, {
+                utils: { label: "Utils", order: 1 },
+            });
+        }
+        test("hides group-only commands from DM overview", () => {
+            const registry = buildScopeRegistry();
+            const dmOverview = renderOverview(registry, "en", undefined, "dm");
+            assert.doesNotMatch(dmOverview, /!g\b/);
+            assert.match(dmOverview, /!d\b/);
+            assert.match(dmOverview, /!b\b/);
+        });
+        test("hides DM-only commands from group overview", () => {
+            const registry = buildScopeRegistry();
+            const groupOverview = renderOverview(registry, "en", undefined, "group");
+            assert.match(groupOverview, /!g\b/);
+            assert.doesNotMatch(groupOverview, /!d\b/);
+            assert.match(groupOverview, /!b\b/);
+        });
+        test("no-scope overview shows all commands", () => {
+            const registry = buildScopeRegistry();
+            const overview = renderOverview(registry, "en");
+            assert.match(overview, /!g\b/);
+            assert.match(overview, /!d\b/);
+            assert.match(overview, /!b\b/);
+        });
+        test("renderCategory respects hiddenOutsideScope", () => {
+            const registry = buildScopeRegistry();
+            const dmCategory = renderCategory(registry, "utils", "en", "dm");
+            assert.ok(dmCategory);
+            assert.doesNotMatch(dmCategory, /!g\b/);
+            assert.match(dmCategory, /!d\b/);
+        });
     });
 });

package/dist/kernel/commandPermissions.js

@@ -2,16 +2,19 @@
  * commandPermissions.ts
  *
  * Permission engine for ManyBot commands.
- * Checks owner, scope, blacklist, whitelist, botAdmin, admin, and cooldown.
+ * Checks dono, owner, scope, allowed_chats, blacklist, whitelist,
+ * botAdmin, admin, and cooldown.
  *
  * Order of evaluation:
- *   1. owner
- *   2. scope
- *   3. blacklist
- *   4. whitelist
- *   5. botAdmin
- *   6. admin
- *   7. cooldown (only consumed if all prior checks pass)
+ *   1. dono       (specific owner JID; otherwise falls through to owner)
+ *   2. owner
+ *   3. scope
+ *   4. allowed_chats  (closed list of JIDs; deny outside)
+ *   5. blacklist
+ *   6. whitelist
+ *   7. botAdmin
+ *   8. admin
+ *   9. cooldown (only consumed if all prior checks pass)
  */
 import { OWNER_NUMBER } from "#config";
 import { normalizeJid } from "#drivers/jid.js";
@@ -37,38 +40,75 @@ export function matchId(targetId, candidate) {
     return false;
 }
 export function matchesAny(targetId, candidates) {
+    if (!targetId)
+        return false;
     return candidates.some(candidate => matchId(targetId, candidate));
 }
+/**
+ * Matches a sender against a list of configured ids (numbers or JIDs),
+ * trying both the LID and PN forms — config today is written in phone
+ * numbers, but a sender whose PN mapping isn't known yet only has a LID
+ * (or, rarely, only a PN when no LID has been learned). Either form
+ * matching is enough.
+ */
+export function matchesSender(sender, candidates) {
+    return matchesAny(sender.lid, candidates) || matchesAny(sender.pn, candidates);
+}
+/** Stable per-sender identity for cooldown/state keys — prefers LID (canonical), falls back to PN. */
+function senderKey(sender) {
+    return sender.lid ?? sender.pn ?? "unknown";
+}
+/**
+ * Cooldown reset key. Format: `<pluginName>:<subId|cmd>` so distinct
+ * plugin-provided commands don't share buckets even when registered
+ * under the same cmd, and the same command under two cmd names doesn't
+ * either. Subcommands reuse the parent's plugin/cmd unless overridden.
+ */
+function cooldownKey(entry) {
+    return `${entry.pluginName ?? "text"}:${entry.cmd}`;
+}
 export async function checkPermission(entry, ctx) {
     const perms = entry.permissions;
     const msgs = perms.messages;
-    // 1. Owner check
+    // 1. dono check (specific owner JID, overrides global OWNER_NUMBER)
+    if (perms.dono) {
+        if (!matchesSender(ctx.sender, [perms.dono])) {
+            return { allowed: false, message: msgs.donoOnly };
+        }
+    }
+    // 2. Owner check
     if (perms.owner) {
-        if (!OWNER_NUMBER || !matchId(ctx.senderId, OWNER_NUMBER)) {
+        if (!OWNER_NUMBER || !matchesSender(ctx.sender, [OWNER_NUMBER])) {
             return { allowed: false, message: msgs.ownerOnly };
         }
     }
-    // 2. Scope check (group | dm | any)
+    // 3. Scope check (group | dm | any)
     if (perms.scope === "group" && !ctx.isGroup) {
         return { allowed: false, message: msgs.wrongScope };
     }
     if (perms.scope === "dm" && ctx.isGroup) {
         return { allowed: false, message: msgs.wrongScope };
     }
-    // 3. Blacklist check
+    // 4. allowed_chats check (closed list of JIDs the command may run in)
+    if (perms.allowedChats && perms.allowedChats.length > 0) {
+        if (!matchesAny(ctx.chatId, perms.allowedChats)) {
+            return { allowed: false, message: msgs.allowedChats };
+        }
+    }
+    // 5. Blacklist check
     if (perms.blacklist) {
         if (ctx.isGroup && perms.blacklist.groups.length > 0) {
             if (matchesAny(ctx.chatId, perms.blacklist.groups)) {
-                return { allowed: false, message: msgs.wrongScope };
+                return { allowed: false, message: msgs.blacklist };
             }
         }
         if (perms.blacklist.users.length > 0) {
-            if (matchesAny(ctx.senderId, perms.blacklist.users)) {
-                return { allowed: false, message: msgs.wrongScope };
+            if (matchesSender(ctx.sender, perms.blacklist.users)) {
+                return { allowed: false, message: msgs.blacklist };
             }
         }
     }
-    // 4. Whitelist check (defined list and outside it -> deny)
+    // 6. Whitelist check (defined list and outside it -> deny)
     if (perms.whitelist) {
         const hasGroupList = perms.whitelist.groups.length > 0;
         const hasUserList = perms.whitelist.users.length > 0;
@@ -81,34 +121,40 @@ export async function checkPermission(entry, ctx) {
             return { allowed: false, message: msgs.wrongScope };
         }
         if (hasUserList) {
-            if (!matchesAny(ctx.senderId, perms.whitelist.users)) {
+            if (!matchesSender(ctx.sender, perms.whitelist.users)) {
                 return { allowed: false, message: msgs.wrongScope };
             }
         }
     }
-    // 5. botAdmin check
+    // 7. botAdmin check
     if (perms.botAdmin) {
+        // Admin status only exists inside a group — outside one, this is a
+        // scope mismatch, not "the bot isn't admin", so use wrongScope
+        // rather than botNotAdmin (which would misleadingly imply the check
+        // was actually evaluated).
         if (!ctx.isGroup) {
-            return { allowed: false, message: msgs.botNotAdmin };
+            return { allowed: false, message: msgs.wrongScope };
         }
         const isBotAdmin = await ctx.isBotAdmin();
         if (!isBotAdmin) {
             return { allowed: false, message: msgs.botNotAdmin };
         }
     }
-    // 6. admin check
+    // 8. admin check
     if (perms.admin) {
+        // Same reasoning as botAdmin above: no group, no admin concept, so
+        // this is wrongScope, not senderNotAdmin.
         if (!ctx.isGroup) {
-            return { allowed: false, message: msgs.senderNotAdmin };
+            return { allowed: false, message: msgs.wrongScope };
         }
         const isSenderAdmin = await ctx.isSenderAdmin();
         if (!isSenderAdmin) {
             return { allowed: false, message: msgs.senderNotAdmin };
         }
     }
-    // 7. Cooldown check (only consumed if all other checks pass)
+    // 9. Cooldown check (only consumed if all other checks pass)
     if (perms.cooldownSeconds > 0) {
-        const key = `${entry.id}:${ctx.senderId}`;
+        const key = `${cooldownKey(entry)}:${senderKey(ctx.sender)}`;
         const now = Date.now();
         const lastUsed = cooldownMap.get(key) ?? 0;
         const elapsedSeconds = (now - lastUsed) / 1000;