abs-zalo-bot 0.2.0

package/src/oa_adapter.js

@@ -0,0 +1,284 @@
+import crypto from "node:crypto";
+
+export const DEFAULT_OA_TOKEN_URL = "https://oauth.zaloapp.com/v4/oa/access_token";
+export const DEFAULT_OA_MESSAGE_URL = "https://openapi.zalo.me/v3.0/oa/message/cs";
+const TOKEN_SKEW_MS = 60_000;
+const MAX_TEXT_LENGTH = 3_500;
+
+function stableHash(parts) {
+  return crypto
+    .createHash("sha256")
+    .update(parts.filter((part) => part !== undefined && part !== null).map(String).join("|"), "utf8")
+    .digest("hex");
+}
+
+function asNonEmptyString(value) {
+  const text = String(value ?? "").trim();
+  return text || "";
+}
+
+function retryableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function safeStatus(response) {
+  return Number.isFinite(Number(response?.status)) ? Number(response.status) : 0;
+}
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    try {
+      const text = await response.text();
+      return text ? JSON.parse(text) : {};
+    } catch {
+      return {};
+    }
+  }
+}
+
+export class OaProviderError extends Error {
+  constructor(code, status = 0, retryable = false) {
+    super(code);
+    // Keep operational metadata non-enumerable so an accidental JSON response
+    // cannot expose provider payloads or credentials.
+    Object.defineProperties(this, {
+      name: { value: "OaProviderError", enumerable: false, configurable: true },
+      code: { value: code, enumerable: false },
+      status: { value: status, enumerable: false },
+      retryable: { value: Boolean(retryable), enumerable: false },
+    });
+  }
+}
+
+export class OaAdapter {
+  constructor({
+    botId,
+    tenantId,
+    appId,
+    appSecret,
+    refreshToken,
+    tokenUrl = DEFAULT_OA_TOKEN_URL,
+    messageUrl = DEFAULT_OA_MESSAGE_URL,
+    fetchImpl = globalThis.fetch,
+    now = () => Date.now(),
+    tokenSkewMs = TOKEN_SKEW_MS,
+  } = {}) {
+    this.botId = asNonEmptyString(botId);
+    this.tenantId = asNonEmptyString(tenantId);
+    this.appId = asNonEmptyString(appId);
+    this.appSecret = asNonEmptyString(appSecret);
+    this.refreshToken = asNonEmptyString(refreshToken);
+    this.tokenUrl = asNonEmptyString(tokenUrl) || DEFAULT_OA_TOKEN_URL;
+    this.messageUrl = asNonEmptyString(messageUrl) || DEFAULT_OA_MESSAGE_URL;
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+    this.tokenSkewMs = Math.max(0, Number(tokenSkewMs) || TOKEN_SKEW_MS);
+    this.cachedToken = null;
+    this.rotatedRefreshToken = null;
+    this.state = "disconnected";
+    this.lastErrorCode = "";
+  }
+
+  endpoints() {
+    return { token_url: this.tokenUrl, message_url: this.messageUrl };
+  }
+
+  status() {
+    const result = {
+      bot_id: this.botId,
+      tenant_id: this.tenantId,
+      adapter: "zalo_oa",
+      state: this.state,
+      ready: Boolean(this.cachedToken && this.cachedToken.expiresAt > this.now()),
+    };
+    if (this.lastErrorCode) result.last_error = this.lastErrorCode;
+    return result;
+  }
+
+  getRotatedRefreshToken() {
+    return this.rotatedRefreshToken;
+  }
+
+  _validateCredentials() {
+    if (!this.botId || !this.tenantId || !this.appId || !this.appSecret || !this.refreshToken) {
+      throw new OaProviderError("credential_missing", 0, false);
+    }
+    if (typeof this.fetchImpl !== "function") {
+      throw new OaProviderError("config_invalid", 0, false);
+    }
+  }
+
+  _cachedTokenIsFresh() {
+    return Boolean(
+      this.cachedToken &&
+        Number.isFinite(this.cachedToken.expiresAt) &&
+        this.cachedToken.expiresAt - this.now() > this.tokenSkewMs,
+    );
+  }
+
+  async getAccessToken() {
+    if (this._cachedTokenIsFresh()) return this.cachedToken.accessToken;
+    this._validateCredentials();
+
+    const form = new URLSearchParams({
+      app_id: this.appId,
+      grant_type: "refresh_token",
+      refresh_token: this.refreshToken,
+      secret_key: this.appSecret,
+    });
+
+    let response;
+    try {
+      response = await this.fetchImpl(this.tokenUrl, {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/x-www-form-urlencoded",
+        },
+        body: form.toString(),
+      });
+    } catch {
+      this.state = "error";
+      this.lastErrorCode = "token_refresh_failed";
+      throw new OaProviderError("token_refresh_failed", 0, true);
+    }
+
+    const status = safeStatus(response);
+    const body = await readJson(response);
+    const accessToken = asNonEmptyString(body?.access_token);
+    const expiresIn = Number(body?.expires_in);
+    if (!response?.ok || !accessToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+      this.state = "error";
+      this.lastErrorCode = "token_refresh_failed";
+      throw new OaProviderError("token_refresh_failed", status, retryableStatus(status));
+    }
+
+    this.cachedToken = {
+      accessToken,
+      expiresAt: this.now() + expiresIn * 1_000,
+    };
+    const rotated = asNonEmptyString(body?.refresh_token);
+    if (rotated) this.rotatedRefreshToken = rotated;
+    this.state = "connected";
+    this.lastErrorCode = "";
+    return accessToken;
+  }
+
+  async sendText({ recipient_id: recipientId, text, correlation_id: correlationId = "" } = {}) {
+    const recipient = asNonEmptyString(recipientId);
+    const message = String(text ?? "");
+    if (!recipient) throw new Error("recipient_required");
+    if (!message.trim()) throw new Error("text_required");
+    if (message.length > MAX_TEXT_LENGTH) throw new Error("text_too_long");
+
+    const accessToken = await this.getAccessToken();
+    let response;
+    try {
+      response = await this.fetchImpl(this.messageUrl, {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/json",
+          access_token: accessToken,
+        },
+        body: JSON.stringify({
+          recipient: { user_id: recipient },
+          message: { text: message },
+        }),
+      });
+    } catch {
+      this.state = "error";
+      this.lastErrorCode = "provider_error";
+      throw new OaProviderError("provider_error", 0, true);
+    }
+
+    const status = safeStatus(response);
+    const body = await readJson(response);
+    if (!response?.ok) {
+      this.state = "error";
+      this.lastErrorCode = "provider_error";
+      throw new OaProviderError("provider_error", status, retryableStatus(status));
+    }
+
+    this.state = "connected";
+    this.lastErrorCode = "";
+    return {
+      ok: true,
+      adapter: "zalo_oa",
+      bot_id: this.botId,
+      tenant_id: this.tenantId,
+      recipient_id: recipient,
+      provider_message_id: asNonEmptyString(
+        body?.message_id ?? body?.data?.message_id ?? body?.message?.message_id,
+      ) || null,
+      correlation_id: asNonEmptyString(correlationId) || null,
+    };
+  }
+}
+
+function parseTimestamp(value) {
+  const numeric = Number(value);
+  if (Number.isFinite(numeric) && numeric > 0) {
+    const milliseconds = numeric < 10_000_000_000 ? numeric * 1_000 : numeric;
+    return new Date(milliseconds).toISOString();
+  }
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : new Date(0).toISOString();
+}
+
+/**
+ * Normalize only text events. This function is deliberately pure: it never
+ * calls an AI provider or sends a reply.
+ */
+export function normalizeOaWebhookEvent({ botId, tenantId, payload } = {}) {
+  const configuredBotId = asNonEmptyString(botId);
+  const configuredTenantId = asNonEmptyString(tenantId);
+  if (!configuredBotId || !configuredTenantId || !payload || typeof payload !== "object") return null;
+
+  const eventType = asNonEmptyString(payload.event_name ?? payload.event ?? payload.event_type);
+  if (eventType !== "user_send_text") return null;
+
+  const providerBotId = asNonEmptyString(payload.bot_id ?? payload.oa_id ?? payload.recipient?.id);
+  if (providerBotId && providerBotId !== configuredBotId && payload.bot_id) return null;
+
+  const message = payload.message && typeof payload.message === "object" ? payload.message : {};
+  const sender = payload.sender && typeof payload.sender === "object" ? payload.sender : {};
+  const senderId = asNonEmptyString(
+    sender.id ?? sender.user_id ?? message.from_id ?? message.fromId ?? payload.from_id,
+  );
+  const text = String(message.text ?? message.content ?? payload.text ?? "");
+  if (!senderId || !text.trim()) return null;
+
+  const providerMessageId = asNonEmptyString(
+    message.message_id ?? message.msg_id ?? payload.message_id,
+  );
+  const receivedAt = parseTimestamp(payload.timestamp ?? payload.time ?? message.timestamp);
+  const eventId = stableHash([
+    configuredBotId,
+    configuredTenantId,
+    eventType,
+    providerMessageId,
+    senderId,
+    receivedAt,
+    text,
+  ]);
+
+  return {
+    event_id: eventId,
+    bot_id: configuredBotId,
+    tenant_id: configuredTenantId,
+    adapter: "zalo_oa",
+    event_type: eventType,
+    sender_id: senderId,
+    sender_name: asNonEmptyString(sender.name ?? sender.display_name ?? message.sender_name) || "",
+    text,
+    is_self: false,
+    received_at: receivedAt,
+    raw_metadata: {
+      provider_message_id: providerMessageId || null,
+      provider_event: eventType,
+    },
+  };
+}

package/src/oa_auto_reply.js

@@ -0,0 +1,75 @@
+import { createOaAdapterMap, getBot } from './bot_registry.js';
+
+function text(value) {
+  return String(value ?? '').trim();
+}
+
+function readAnswer(payload) {
+  return text(payload?.answer).slice(0, 3_500);
+}
+
+// This worker is reachable only from an already verified, normalized OA event.
+// It never offers a public send endpoint, so a reply cannot be triggered without
+// a customer message arriving at the signed webhook first.
+export function createOaAutoReplyWorker({
+  registry,
+  adapters = createOaAdapterMap({ registry }),
+  publicChatUrl = process.env.ABS_BRAIN_CHAT_URL || '',
+  publicBridgeToken = process.env.ABS_BRAIN_TOKEN || '',
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+} = {}) {
+  const seenEvents = new Set();
+  const recentBySender = new Map();
+
+  function allowedInbound(bot, event) {
+    if (!bot || bot.enabled === false || bot.adapter !== 'zalo_oa') return { allow: false, reason: 'bot_disabled' };
+    if (bot.policy?.mode !== 'inbound_auto_reply') return { allow: false, reason: 'inbound_auto_reply_disabled' };
+    if (!text(event?.sender_id) || !text(event?.text)) return { allow: false, reason: 'event_invalid' };
+    if (!text(publicBridgeToken)) return { allow: false, reason: 'public_bridge_token_missing' };
+    const key = `${bot.bot_id}:${event.sender_id}`;
+    const hour = 60 * 60_000;
+    const history = (recentBySender.get(key) || []).filter((at) => now() - at < hour);
+    const limit = Math.max(1, Number(bot.policy?.max_messages_per_hour) || 20);
+    if (history.length >= limit) return { allow: false, reason: 'sender_rate_limited' };
+    recentBySender.set(key, [...history, now()]);
+    return { allow: true, key };
+  }
+
+  async function handle(event) {
+    const bot = getBot(registry, event?.bot_id);
+    if (seenEvents.has(event?.event_id)) return { ok: true, skipped: 'duplicate_event' };
+    const decision = allowedInbound(bot, event);
+    if (!decision.allow) return { ok: true, skipped: decision.reason };
+    try {
+      const response = await fetchImpl(publicChatUrl, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          [process.env.ABS_BRAIN_TOKEN_HEADER || 'x-abs-token']: publicBridgeToken,
+          [process.env.ABS_BRAIN_ID_HEADER || 'x-abs-external-id']: `zalo-oa:${bot.bot_id}:${event.sender_id}`,
+        },
+        body: JSON.stringify({ message: event.text, channel: 'zalo-oa' }),
+      });
+      const payload = await response.json().catch(() => ({}));
+      const answer = readAnswer(payload);
+      if (!response.ok || !answer) return { ok: false, error: 'public_chat_unavailable' };
+
+      const adapter = adapters.get(bot.bot_id);
+      if (!adapter) return { ok: false, error: 'oa_adapter_unavailable' };
+      const delivery = await adapter.sendText({
+        recipient_id: event.sender_id,
+        text: answer,
+        correlation_id: event.event_id,
+      });
+      // Mark only after provider acceptance. A temporary chat/provider failure
+      // must not make the customer's message permanently unanswerable.
+      seenEvents.add(event.event_id);
+      return { ok: true, delivered: true, delivery };
+    } catch (error) {
+      return { ok: false, error: 'auto_reply_failed' };
+    }
+  }
+
+  return { handle };
+}

package/src/oa_policy.js

@@ -0,0 +1,32 @@
+const MAX_TEXT_LENGTH = 3_500;
+
+function clean(value) {
+  return String(value ?? "").trim();
+}
+
+export function evaluateOaOutbound({ bot, recipientId, text } = {}) {
+  const mode = clean(bot?.policy?.mode || "disabled").toLowerCase();
+  const recipient = clean(recipientId);
+  const body = String(text ?? "");
+
+  if (!bot || bot.enabled === false) return { allow: false, reason: "bot_disabled", mode };
+  if (mode === "disabled") return { allow: false, reason: "bot_disabled", mode };
+  if (mode === "paused") return { allow: false, reason: "bot_paused", mode };
+  if (!recipient) return { allow: false, reason: "recipient_required", mode };
+  if (!body.trim()) return { allow: false, reason: "text_required", mode };
+  if (body.length > MAX_TEXT_LENGTH) return { allow: false, reason: "text_too_long", mode };
+  if (mode !== "approved_send") {
+    return { allow: false, reason: "outbound_requires_approval", mode };
+  }
+
+  const allowlist = Array.isArray(bot.policy?.allow_user_ids)
+    ? bot.policy.allow_user_ids.map(clean).filter(Boolean)
+    : [];
+  if (!allowlist.length) return { allow: false, reason: "recipient_allowlist_empty", mode };
+  if (!allowlist.includes(recipient)) {
+    return { allow: false, reason: "recipient_not_allowlisted", mode };
+  }
+  return { allow: true, reason: "approved", mode };
+}
+
+export const OA_MAX_TEXT_LENGTH = MAX_TEXT_LENGTH;

package/src/oa_webhook.js

@@ -0,0 +1,95 @@
+import crypto from "node:crypto";
+
+import { getBot } from "./bot_registry.js";
+import { normalizeOaWebhookEvent } from "./oa_adapter.js";
+
+const DEFAULT_MAX_BODY_BYTES = 256 * 1024;
+
+function bytesOf(rawBody) {
+  if (rawBody == null) return 0;
+  if (Buffer.isBuffer(rawBody)) return rawBody.byteLength;
+  return Buffer.byteLength(String(rawBody), "utf8");
+}
+
+function rawBytes(rawBody, body) {
+  if (rawBody != null) return Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), "utf8");
+  return Buffer.from(JSON.stringify(body ?? {}), "utf8");
+}
+
+function signatureFrom(req) {
+  return String(
+    req?.headers?.["x-zalo-signature"] ??
+      req?.headers?.["x-signature"] ??
+      req?.headers?.["x-zalo-webhook-signature"] ??
+      "",
+  ).trim();
+}
+
+export function verifyWebhookSignature({ rawBody, signature, secret } = {}) {
+  const configuredSecret = String(secret ?? "");
+  if (!configuredSecret) return true;
+  const provided = String(signature ?? "").trim().toLowerCase();
+  if (!provided || !/^[a-f0-9]{64}$/.test(provided)) return false;
+  const expected = crypto.createHmac("sha256", configuredSecret).update(rawBytes(rawBody)).digest("hex");
+  const left = Buffer.from(provided, "hex");
+  const right = Buffer.from(expected, "hex");
+  return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+
+function reply(res, statusCode, payload) {
+  if (typeof res?.status === "function" && typeof res?.json === "function") {
+    return res.status(statusCode).json(payload);
+  }
+  if (res) {
+    res.statusCode = statusCode;
+    res.payload = payload;
+  }
+  return res;
+}
+
+/**
+ * Express-compatible OA webhook handler. It performs ingress validation and
+ * normalization only. The caller decides whether/how to enqueue a workflow.
+ */
+export function createOaWebhookHandler({
+  registry,
+  webhookSecret = process.env.ZALO_OA_WEBHOOK_SECRET || "",
+  onEvent = async () => {},
+  maxBodyBytes = DEFAULT_MAX_BODY_BYTES,
+} = {}) {
+  return async function oaWebhookHandler(req, res) {
+    const botId = String(req?.params?.bot_id || "").trim();
+    const bot = getBot(registry, botId);
+    if (!bot) return reply(res, 404, { ok: false, error: "bot_not_found" });
+    if (!bot.enabled) return reply(res, 409, { ok: false, error: "bot_disabled" });
+
+    const rawBody = req?.rawBody ?? req?.bodyRaw ?? null;
+    const bodySize = bytesOf(rawBody) || bytesOf(req?.body ? JSON.stringify(req.body) : "");
+    if (bodySize > Math.max(1, Number(maxBodyBytes) || DEFAULT_MAX_BODY_BYTES)) {
+      return reply(res, 413, { ok: false, error: "webhook_body_too_large" });
+    }
+
+    if (!verifyWebhookSignature({ rawBody: rawBody ?? JSON.stringify(req?.body ?? {}), signature: signatureFrom(req), secret: webhookSecret })) {
+      return reply(res, 401, { ok: false, error: "webhook_signature_invalid" });
+    }
+
+    const event = normalizeOaWebhookEvent({
+      botId: bot.bot_id,
+      tenantId: bot.tenant_id,
+      payload: req?.body,
+    });
+    if (!event) return reply(res, 200, { ok: true, ignored: true });
+
+    // Acknowledge first. Queue/worker failures must not cause provider retries
+    // to duplicate a message; errors are exposed through the caller's queue.
+    const response = reply(res, 200, { ok: true, event_id: event.event_id });
+    try {
+      await Promise.resolve(onEvent(event));
+    } catch {
+      // Deliberately do not rewrite an already acknowledged provider response.
+    }
+    return response;
+  };
+}
+
+export const OA_WEBHOOK_MAX_BODY_BYTES = DEFAULT_MAX_BODY_BYTES;

package/src/onboarding.js

@@ -0,0 +1,102 @@
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3871;
+const DEFAULT_ACCOUNT = "default";
+const DEFAULT_LOCAL_PORT = 13871;
+
+function port(value, name, fallback) {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    throw new Error(`${name} must be an integer between 1 and 65535`);
+  }
+  return parsed;
+}
+
+function text(value, fallback = "") {
+  const result = String(value ?? fallback).trim();
+  return result || fallback;
+}
+
+function shellArg(value) {
+  const raw = text(value);
+  if (!raw || /[\r\n]/.test(raw)) throw new Error("SSH value cannot be empty or multiline");
+  if (/^[A-Za-z0-9._:@%+-]+$/.test(raw)) return raw;
+  return `'${raw.replaceAll("'", "'\\''")}'`;
+}
+
+function baseUrl(value, fallback) {
+  const raw = text(value, fallback).replace(/\/+$/, "");
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error("dashboard URL must be an absolute http(s) URL");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error("dashboard URL must use http or https");
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+export function buildSshTunnelCommand({
+  localPort = DEFAULT_LOCAL_PORT,
+  remotePort = DEFAULT_PORT,
+  sshUser,
+  sshHost,
+} = {}) {
+  const local = port(localPort, "localPort", DEFAULT_LOCAL_PORT);
+  const remote = port(remotePort, "remotePort", DEFAULT_PORT);
+  const user = shellArg(sshUser || "user");
+  const host = shellArg(sshHost || "your-vps-host");
+  return `ssh -N -L ${local}:127.0.0.1:${remote} ${user}@${host}`;
+}
+
+export function buildOnboardingInfo({
+  host = DEFAULT_HOST,
+  port: dashboardPort = DEFAULT_PORT,
+  accountId = DEFAULT_ACCOUNT,
+  localPort = DEFAULT_LOCAL_PORT,
+  sshUser = "user",
+  sshHost = "your-vps-host",
+  publicUrl = "",
+} = {}) {
+  const bindHost = text(host, DEFAULT_HOST);
+  const remotePort = port(dashboardPort, "port", DEFAULT_PORT);
+  const account = encodeURIComponent(text(accountId, DEFAULT_ACCOUNT));
+  const localHost = bindHost === "0.0.0.0" || bindHost === "::" ? DEFAULT_HOST : bindHost;
+  const dashboardUrl = `http://${localHost}:${remotePort}`;
+  const connectUrl = `${dashboardUrl}/connect`;
+  const tunnelCommand = buildSshTunnelCommand({
+    localPort,
+    remotePort,
+    sshUser,
+    sshHost,
+  });
+  const publicBase = publicUrl ? baseUrl(publicUrl, dashboardUrl) : "";
+
+  return {
+    dashboard_url: dashboardUrl,
+    connect_url: connectUrl,
+    qr_api_url: `${dashboardUrl}/api/accounts/${account}/qr`,
+    qr_location: "browser",
+    note: "Open the connect URL in a browser. The QR is never printed in logs or sent to chat.",
+    vps: {
+      browser_url: `http://127.0.0.1:${localPort}/connect`,
+      ssh_tunnel_command: tunnelCommand,
+      ...(publicBase ? { public_url: `${publicBase}/connect` } : {}),
+    },
+  };
+}
+
+export function onboardingFromEnv(env = process.env) {
+  return buildOnboardingInfo({
+    host: env.HOST || env.DASHBOARD_BIND || DEFAULT_HOST,
+    port: env.PORT || env.DASHBOARD_PORT || DEFAULT_PORT,
+    accountId: env.DEFAULT_ACCOUNT_ID || DEFAULT_ACCOUNT,
+    localPort: env.QR_LOCAL_PORT || DEFAULT_LOCAL_PORT,
+    sshUser: env.DASHBOARD_SSH_USER || env.SSH_USER || "user",
+    sshHost: env.DASHBOARD_SSH_HOST || env.SSH_HOST || "your-vps-host",
+    publicUrl: env.DASHBOARD_PUBLIC_URL || "",
+  });
+}
+
+export { DEFAULT_LOCAL_PORT };