abs-zalo-bot 0.2.0

package/scripts/public-gate.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * Offline release gates for the public starter.
+ *
+ * The scanner intentionally ignores local runtime state (.env, data, sessions,
+ * QR images, databases, logs, node_modules). Those paths are checked by the
+ * repository ignore rules and must never be staged for a release.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { loadConfig } from "../src/config.js";
+import { validateBotRegistry } from "../src/bot_registry.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const IGNORED_DIRS = new Set([".git", "node_modules", "data", "coverage"]);
+const IGNORED_FILES = new Set([".env", "bots.json"]);
+const SAFE_ENV_FILES = new Set([".env.example"]);
+const TEXT_EXTENSIONS = new Set([
+  ".cjs",
+  ".css",
+  ".html",
+  ".js",
+  ".json",
+  ".md",
+  ".mjs",
+  ".service",
+  ".sh",
+  ".toml",
+  ".ts",
+  ".txt",
+  ".yml",
+  ".yaml",
+]);
+
+function walk(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && IGNORED_DIRS.has(entry.name)) continue;
+    if (entry.isFile() && IGNORED_FILES.has(entry.name) && !SAFE_ENV_FILES.has(entry.name)) continue;
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(absolute, out);
+    else out.push(absolute);
+  }
+  return out;
+}
+
+function relative(file) {
+  return path.relative(ROOT, file) || ".";
+}
+
+function publicFiles() {
+  return walk(ROOT).filter((file) => {
+    const name = path.basename(file);
+    if (IGNORED_FILES.has(name) && !SAFE_ENV_FILES.has(name)) return false;
+    return true;
+  });
+}
+
+function readText(file) {
+  const ext = path.extname(file).toLowerCase();
+  if (!TEXT_EXTENSIONS.has(ext) && path.basename(file) !== ".gitignore") return null;
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function fail(message, details = []) {
+  const payload = { ok: false, error: message };
+  if (details.length) payload.details = details;
+  console.error(JSON.stringify(payload, null, 2));
+  process.exitCode = 1;
+}
+
+function pass(name, details = {}) {
+  console.log(JSON.stringify({ ok: true, check: name, ...details }, null, 2));
+}
+
+function validateConfig() {
+  const packagePath = path.join(ROOT, "package.json");
+  const registryPath = path.join(ROOT, "config", "bots.example.json");
+  let pkg;
+  let registry;
+  try {
+    pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+    registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+  } catch (error) {
+    fail("public_config_parse_failed", [String(error?.message || error)]);
+    return;
+  }
+
+  let normalized;
+  let config;
+  try {
+    normalized = validateBotRegistry(registry);
+    config = loadConfig(path.join(ROOT, "config.toml"));
+  } catch (error) {
+    fail("public_config_validation_failed", [String(error?.message || error)]);
+    return;
+  }
+
+  const issues = [];
+  // This package is intentionally publishable to npm. Instead of forbidding
+  // publish outright, enforce that a publish cannot happen half-configured:
+  // metadata must be complete and the tarball allowlist must be explicit,
+  // so runtime/secret paths can never be shipped by accident.
+  if (pkg.private === true) issues.push("package_marked_private_but_publish_metadata_expected");
+  if (!pkg.license) issues.push("package_license_required");
+  if (!pkg.repository?.url) issues.push("package_repository_url_required");
+  if (!Array.isArray(pkg.files) || pkg.files.length === 0) {
+    issues.push("package_files_allowlist_required");
+  } else {
+    const forbidden = ["data", "data/", ".env", "test", "test/", "config/bots.json"];
+    const leaked = pkg.files.filter((entry) =>
+      forbidden.some((bad) => entry === bad || entry.startsWith(`${bad}/`)),
+    );
+    if (leaked.length) issues.push(`package_files_must_not_ship_runtime_paths:${leaked.join(",")}`);
+  }
+  if (config.read_only_source !== true) issues.push("example_must_enable_read_only_source");
+  if (config.destination.group_id) issues.push("example_destination_id_must_be_empty");
+  if (normalized.bots.some((bot) => bot.policy.mode !== "draft_first")) {
+    issues.push("example_oa_policy_must_be_draft_first");
+  }
+  if (normalized.bots.some((bot) => bot.adapter === "zalo_oa" && !bot.credential)) {
+    issues.push("oa_credential_references_missing");
+  }
+  if (issues.length) {
+    fail("public_config_policy_failed", issues);
+    return;
+  }
+
+  pass("validate-config", {
+    package: { name: pkg.name, version: pkg.version, node: pkg.engines?.node || "" },
+    registry_bots: normalized.bots.length,
+    default_account_id: config.default_account_id,
+    destination_configured: Boolean(config.destination.group_id),
+    read_only_source: config.read_only_source,
+  });
+}
+
+function secretScan() {
+  const findings = [];
+  const files = publicFiles();
+  const privateKey = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+  const providerToken = /\b(?:sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,})\b/;
+  const longNumericId = /\b\d{15,22}\b/;
+  const vnPhoneLiteral = /(?<![\d])(?:\+?84|0)\d{8,10}(?!\d)/;
+  const assignment = /^\s*(?:DASHBOARD_TOKEN|HERMES_API_SERVER_KEY|HERMES_WEBHOOK_TOKEN|ZALO_OA_WEBHOOK_SECRET)\s*=\s*([^#\s]+)/;
+  const allowedPlaceholder = /^(?:$|change-me|<[^>]+>|\[REDACTED\]|\[redacted\]|[A-Za-z0-9._-]*fixture[A-Za-z0-9._-]*)$/i;
+
+  for (const file of files) {
+    const text = readText(file);
+    if (text == null) continue;
+    const lines = text.split(/\r?\n/);
+    lines.forEach((line, index) => {
+      const lineNumber = index + 1;
+      if (privateKey.test(line) || providerToken.test(line)) {
+        findings.push(`${relative(file)}:${lineNumber}:credential-pattern`);
+      }
+      if (longNumericId.test(line)) {
+        findings.push(`${relative(file)}:${lineNumber}:long-numeric-identifier`);
+      }
+      if (vnPhoneLiteral.test(line)) {
+        findings.push(`${relative(file)}:${lineNumber}:phone-like-literal`);
+      }
+      const match = line.match(assignment);
+      if (match && !allowedPlaceholder.test(match[1])) {
+        findings.push(`${relative(file)}:${lineNumber}:non-placeholder-secret-assignment`);
+      }
+    });
+  }
+
+  const envPath = path.join(ROOT, ".env");
+  const ignoredRuntimePresent = [];
+  if (fs.existsSync(envPath)) ignoredRuntimePresent.push(".env");
+  if (fs.existsSync(path.join(ROOT, "data"))) ignoredRuntimePresent.push("data/");
+
+  if (findings.length) {
+    fail("public_secret_scan_failed", findings);
+    return;
+  }
+  pass("secret-scan", {
+    files_scanned: files.length,
+    runtime_paths_ignored: ignoredRuntimePresent,
+  });
+}
+
+function syntaxCheck() {
+  const files = publicFiles().filter((file) => path.extname(file) === ".js");
+  const failures = [];
+  for (const file of files) {
+    const result = spawnSync(process.execPath, ["--check", file], {
+      cwd: ROOT,
+      encoding: "utf8",
+    });
+    if (result.status !== 0) {
+      failures.push({ file: relative(file), output: String(result.stderr || result.stdout || "").trim().slice(0, 500) });
+    }
+  }
+  if (failures.length) {
+    fail("javascript_syntax_failed", failures);
+    return;
+  }
+  pass("syntax-check", { javascript_files: files.length });
+}
+
+const command = process.argv[2] || "";
+if (command === "validate-config") validateConfig();
+else if (command === "secret-scan") secretScan();
+else if (command === "syntax-check") syntaxCheck();
+else {
+  fail("usage", ["node scripts/public-gate.js validate-config|secret-scan|syntax-check"]);
+}

package/scripts/setup.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * Friendly local setup/doctor entrypoint.
+ *
+ * Safe by design:
+ * - never overwrites .env or config/bots.json;
+ * - never asks for or prints secrets;
+ * - never logs in, scans QR, enters OTP/PIN, or sends a message;
+ * - runs deterministic local verification before telling the operator to start.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { buildOnboardingInfo } from "../src/onboarding.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MIN_NODE = { major: 22, minor: 5 };
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+
+function parseArgs(argv) {
+  const flags = new Set();
+  let command = "setup";
+  for (const arg of argv) {
+    if (arg.startsWith("--")) flags.add(arg);
+    else if (!command || command === "setup") command = arg;
+  }
+  return { command, flags };
+}
+
+function nodeVersion() {
+  const match = process.versions.node.match(/^(\d+)\.(\d+)/);
+  return match ? { major: Number(match[1]), minor: Number(match[2]), raw: process.versions.node } : null;
+}
+
+function ensureNode() {
+  const version = nodeVersion();
+  if (!version || version.major < MIN_NODE.major || (version.major === MIN_NODE.major && version.minor < MIN_NODE.minor)) {
+    throw new Error(
+      `Node.js ${MIN_NODE.major}.${MIN_NODE.minor}+ is required; detected ${version?.raw || process.version}. Install a current Node.js LTS and run setup again.`,
+    );
+  }
+  console.log(`PASS  Node.js ${version.raw}`);
+}
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(ROOT, relativePath));
+}
+
+function ensureDir(relativePath, mode = 0o700) {
+  const absolute = path.join(ROOT, relativePath);
+  fs.mkdirSync(absolute, { recursive: true, mode });
+  try {
+    fs.chmodSync(absolute, mode);
+  } catch {
+    // Windows and restricted filesystems may not support chmod; the directory
+    // still exists and the operator gets a concrete path to inspect.
+  }
+}
+
+function copyIfMissing(sourceRelative, targetRelative, mode = 0o600) {
+  const source = path.join(ROOT, sourceRelative);
+  const target = path.join(ROOT, targetRelative);
+  if (fs.existsSync(target)) {
+    console.log(`KEEP  ${targetRelative} already exists (not overwritten)`);
+    return false;
+  }
+  if (!fs.existsSync(source)) throw new Error(`Missing public template: ${sourceRelative}`);
+  fs.copyFileSync(source, target);
+  try {
+    fs.chmodSync(target, mode);
+  } catch {
+    // Best effort on platforms without POSIX permissions.
+  }
+  console.log(`CREATE ${targetRelative}`);
+  return true;
+}
+
+function ensureLocalFiles() {
+  copyIfMissing(".env.example", ".env", 0o600);
+  copyIfMissing("config/bots.example.json", "config/bots.json", 0o600);
+  ensureDir("data", 0o700);
+  ensureDir("data/sessions", 0o700);
+  ensureDir("data/qr", 0o700);
+  ensureDir("data/logs", 0o700);
+}
+
+function run(label, command, args, { allowFailure = false } = {}) {
+  console.log(`RUN   ${label}`);
+  const result = spawnSync(command, args, {
+    cwd: ROOT,
+    env: { ...process.env, FORCE_COLOR: "0" },
+    stdio: "inherit",
+  });
+  if (result.error) throw result.error;
+  const code = Number.isInteger(result.status) ? result.status : 1;
+  console.log(`${code === 0 ? "PASS" : "FAIL"}  ${label} (exit ${code})`);
+  if (code !== 0 && !allowFailure) {
+    throw new Error(`${label} failed with exit code ${code}`);
+  }
+  return code;
+}
+
+function npmRun(script, options = {}) {
+  return run(`npm run ${script}`, npmCommand, ["run", script], options);
+}
+
+function checkExpectedFiles() {
+  const required = [
+    ".env.example",
+    "config/bots.example.json",
+    "config.toml",
+    "public/index.html",
+    "package-lock.json",
+  ];
+  const missing = required.filter((file) => !exists(file));
+  if (missing.length) throw new Error(`Missing required files: ${missing.join(", ")}`);
+  console.log(`PASS  Required public files (${required.length})`);
+}
+
+function readLocalEnvValue(key) {
+  if (!exists(".env")) return "";
+  const text = fs.readFileSync(path.join(ROOT, ".env"), "utf8");
+  const line = text.split(/\r?\n/).find((item) => item.trim().startsWith(`${key}=`));
+  if (!line) return "";
+  return line.slice(key.length + 1).trim().replace(/^['"]|['"]$/g, "");
+}
+
+function localStatus() {
+  const envPresent = exists(".env");
+  const botsPresent = exists("config/bots.json");
+  const dataPresent = exists("data");
+  const token = readLocalEnvValue("DASHBOARD_TOKEN");
+  const tokenConfigured = Boolean(token && token !== "change-me");
+  return { envPresent, botsPresent, dataPresent, tokenConfigured };
+}
+
+function printDashboardInfo() {
+  const env = exists(".env") ? fs.readFileSync(path.join(ROOT, ".env"), "utf8") : "";
+  const readEnv = (key, fallback) => {
+    const line = env.split(/\r?\n/).find((item) => item.trim().startsWith(`${key}=`));
+    return line ? line.slice(key.length + 1).trim().replace(/^['"]|['"]$/g, "") || fallback : fallback;
+  };
+  const host = readEnv("HOST", "127.0.0.1");
+  const port = readEnv("PORT", "3871");
+  const token = readEnv("DASHBOARD_TOKEN", "");
+  const onboarding = buildOnboardingInfo({
+    host,
+    port,
+    accountId: readEnv("DEFAULT_ACCOUNT_ID", "default"),
+    localPort: readEnv("QR_LOCAL_PORT", "13871"),
+    sshUser: readEnv("DASHBOARD_SSH_USER", "user"),
+    sshHost: readEnv("DASHBOARD_SSH_HOST", "your-vps-host"),
+    publicUrl: readEnv("DASHBOARD_PUBLIC_URL", ""),
+  });
+  console.log(JSON.stringify({
+    ok: true,
+    bind: `${host}:${port}`,
+    dashboard_url: onboarding.dashboard_url,
+    connect_url: onboarding.connect_url,
+    qr_api_url: onboarding.qr_api_url,
+    vps: onboarding.vps,
+    dashboard_token_configured: Boolean(token && token !== "change-me"),
+    note: "Open connect_url in a browser. URLs only; no QR image or token value is printed.",
+  }, null, 2));
+}
+
+function doctor() {
+  ensureNode();
+  checkExpectedFiles();
+  const local = localStatus();
+  const issues = [];
+  if (!local.envPresent) issues.push(".env_missing_run_setup");
+  if (!local.botsPresent) issues.push("config/bots.json_missing_run_setup");
+  if (!local.dataPresent) issues.push("data_missing_run_setup");
+  if (!local.tokenConfigured) issues.push("dashboard_token_not_configured_local_only_warning");
+  console.log(JSON.stringify({
+    ok: issues.every((issue) => issue.endsWith("warning")),
+    local: {
+      env_present: local.envPresent,
+      bots_config_present: local.botsPresent,
+      data_present: local.dataPresent,
+      dashboard_token_configured: local.tokenConfigured,
+    },
+    issues,
+  }, null, 2));
+  if (issues.some((issue) => issue.includes("missing"))) return 1;
+
+  npmRun("validate-config");
+  npmRun("secret-scan");
+  npmRun("syntax-check");
+  npmRun("self-check");
+  return 0;
+}
+
+function setup(flags) {
+  ensureNode();
+  checkExpectedFiles();
+  ensureLocalFiles();
+  if (!flags.has("--skip-install")) npmRun("install:locked");
+  npmRun("test");
+  npmRun("validate-config");
+  npmRun("secret-scan");
+  npmRun("syntax-check");
+  npmRun("self-check");
+  printDashboardInfo();
+  console.log("\nSetup complete. No login, QR scan, OTP/PIN entry, or message send was performed.");
+  console.log("Next: npm start, then open the dashboard URL above and scan QR manually if using Personal QR.");
+  if (flags.has("--start")) {
+    console.log("\nStarting the foreground server. Press Ctrl+C to stop it.");
+    return run("npm start", npmCommand, ["start"]);
+  }
+  return 0;
+}
+
+function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  try {
+    if (command === "setup" || command === "install") process.exitCode = setup(flags);
+    else if (command === "doctor") process.exitCode = doctor();
+    else if (command === "dashboard-info") printDashboardInfo();
+    else {
+      console.error("Usage: node scripts/setup.js [setup|doctor|dashboard-info] [--non-interactive] [--skip-install] [--start]");
+      process.exitCode = 2;
+    }
+  } catch (error) {
+    console.error(`\nSETUP BLOCKED: ${String(error?.message || error)}`);
+    console.error("No credential, OTP/PIN, QR login, or live message action was attempted.");
+    process.exitCode = 1;
+  }
+}
+
+main();

package/src/abs_telemetry.js

@@ -0,0 +1,60 @@
+// Privacy-minimal Zalo -> ABS adapter.  This is not a reply mechanism and
+// does not read, persist, or forward message content.  It records only the
+// outcome of an explicit Zalo-to-brain turn, fail-open.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// Đường dẫn ledger do người triển khai khai báo qua ABS_LEDGER_PATH.
+// Không hardcode đường dẫn máy chủ nào: repo public phải chạy được ở mọi nơi.
+
+function durationBucket(value) {
+  const milliseconds = Number(value || 0);
+  if (!Number.isFinite(milliseconds) || milliseconds < 0) return "unknown";
+  if (milliseconds < 100) return "lt_100ms";
+  if (milliseconds < 1_000) return "lt_1s";
+  if (milliseconds < 10_000) return "lt_10s";
+  return "gte_10s";
+}
+
+function ledgerPath() {
+  const configured = process.env.ABS_LEDGER_PATH || "";
+  for (const candidate of [configured]) {
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return "";
+}
+
+/**
+ * Record a single local-only Zalo brain outcome. Raw source_id is provided only
+ * through stdin to the Python ledger, which salts it before SQLite insertion.
+ */
+export function recordZaloBrainTurn({ event, outcome = "unknown", durationMs, runner = spawnSync }) {
+  try {
+    const rawChatId = String(event?.source_id || "");
+    const conversationType = String(event?.source_type || "unknown");
+    const ledger = ledgerPath();
+    if (!ledger || !rawChatId || !["dm", "group"].includes(conversationType)) {
+      return { ok: false, reason: "telemetry_unavailable" };
+    }
+    const input = JSON.stringify({
+      event_type: "zalo_brain_turn",
+      platform: "zalo",
+      raw_chat_id: rawChatId,
+      conversation_type: conversationType,
+      metadata: {
+        outcome: outcome === "success" ? "success" : "non_success",
+        duration_bucket: durationBucket(durationMs),
+      },
+    });
+    const child = runner("python3", [ledger, "record-stdin"], {
+      input,
+      encoding: "utf8",
+      stdio: ["pipe", "ignore", "ignore"],
+      timeout: 2_000,
+    });
+    return { ok: child?.status === 0, reason: child?.status === 0 ? "recorded" : "telemetry_failed" };
+  } catch {
+    return { ok: false, reason: "telemetry_failed" };
+  }
+}

package/src/ask.js

@@ -0,0 +1,7 @@
+// Legacy ask helpers kept for tests/MCP; Phase-1 brain path lives in inbound_router.js
+export {
+  isBotCommand,
+  isBotCommand as looksLikeAsk,
+  handleBotBrainCommand as handleDestinationAsk,
+} from "./inbound_router.js";
+export { resolveDestinationByName } from "./discovery.js";