@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/zalo/skills/zalo-oa-webhook.md

@@ -0,0 +1,189 @@
+---
+name: zalo-oa-webhook
+pack: "@rune/zalo"
+description: "Set up and handle Zalo OA webhook server — signature verification, event routing, idempotency, and tunnel for local development."
+model: sonnet
+tools: "Read, Glob, Grep, Bash, Write, Edit"
+---
+
+# zalo-oa-webhook
+
+Set up and handle Zalo OA webhook server — signature verification, event routing, idempotency, and tunnel for local development.
+
+#### Workflow
+
+**Step 1 — Register webhook at Zalo Developer Portal**
+Go to [developers.zalo.me](https://developers.zalo.me) → select App → **App Settings → Webhook**. Enter your HTTPS endpoint URL (e.g., `https://your-domain.com/webhook/zalo`). Zalo sends `POST` requests to this URL for every OA event. The URL must be HTTPS — no plain HTTP. For local dev, use ngrok: `ngrok http 3000` and paste the `https://` tunnel URL. Remember to update the URL when the tunnel restarts.
+
+**Step 2 — Verify signature on every request (CRITICAL)**
+Every request from Zalo includes `X-ZEvent-Signature` header — HMAC-SHA256 of the raw request body, signed with your **OA Secret Key** (not the App Secret — different keys). Verify before processing. Use `crypto.timingSafeEqual` to prevent timing attacks. Reject with 403 if invalid.
+
+```typescript
+import crypto from 'crypto'
+
+function verifyWebhookSignature(
+  body: string,
+  signature: string,
+  oaSecretKey: string
+): boolean {
+  const computed = crypto
+    .createHmac('sha256', oaSecretKey)
+    .update(body)
+    .digest('hex')
+  return crypto.timingSafeEqual(
+    Buffer.from(computed, 'hex'),
+    Buffer.from(signature, 'hex')
+  )
+}
+```
+
+NEVER skip verification — even in development. NEVER use `===` string compare (timing leak).
+
+**Step 3 — Respond within 5 seconds**
+Zalo expects `200 OK` within 5 seconds or it marks the delivery failed and retries up to 3 times. Acknowledge immediately, then process asynchronously:
+
+```typescript
+// Return 200 first, then process
+return c.json({ received: true })  // respond immediately
+await queue.push(event)            // async processing
+```
+
+**Step 4 — Implement idempotency**
+Retries cause duplicate events. Use `msg_id` (present on message events) to deduplicate. Check before processing, mark as processed after:
+
+```typescript
+const processedIds = new Set<string>() // or Redis for production
+
+async function idempotentHandle(event: ZaloEvent): Promise<void> {
+  const id = event.message?.msg_id ?? `${event.event_name}:${event.timestamp}`
+  if (processedIds.has(id)) return
+  processedIds.add(id)
+  await routeEvent(event)
+}
+```
+
+**Step 5 — Route events by event_name**
+
+| event_name | Trigger | Key payload fields |
+|---|---|---|
+| `user_send_text` | User sends text | `sender.id`, `message.text`, `message.msg_id` |
+| `user_send_image` | User sends image | `sender.id`, `message.attachments[].payload.url` |
+| `user_send_file` | User sends file | `sender.id`, `message.attachments[]` |
+| `user_send_sticker` | User sends sticker | `sender.id`, `message.attachments[]` |
+| `user_send_location` | User sends location | `sender.id`, `message.attachments[].payload.coordinates` |
+| `follow` | User follows OA | `follower.id` |
+| `unfollow` | User unfollows OA | `follower.id` |
+| `user_click_button` | User clicks button | `sender.id`, `message.text` (button payload) |
+| `oa_send_text` | OA message delivered | — |
+
+Note: naming is inconsistent — messages use `user_send_*` prefix, follow/unfollow do not.
+
+#### Server Implementations
+
+**Hono (recommended — edge-ready)**
+
+```typescript
+import { Hono } from 'hono'
+import { serve } from '@hono/node-server'
+import crypto from 'crypto'
+
+const OA_SECRET_KEY = process.env.ZALO_OA_SECRET_KEY!
+const app = new Hono()
+
+app.post('/webhook/zalo', async (c) => {
+  const signature = c.req.header('X-ZEvent-Signature') ?? ''
+  const body = await c.req.text() // raw body — MUST use text(), not json()
+
+  if (!verifyWebhookSignature(body, signature, OA_SECRET_KEY)) {
+    return c.json({ error: 'Invalid signature' }, 403)
+  }
+
+  const event: ZaloEvent = JSON.parse(body)
+  c.executionCtx?.waitUntil(idempotentHandle(event)) // non-blocking
+  return c.json({ received: true })
+})
+
+async function routeEvent(event: ZaloEvent): Promise<void> {
+  switch (event.event_name) {
+    case 'user_send_text':    return handleTextMessage(event)
+    case 'user_send_image':   return handleImageMessage(event)
+    case 'user_send_file':    return handleFileMessage(event)
+    case 'user_send_location': return handleLocation(event)
+    case 'follow':            return handleFollow(event)
+    case 'unfollow':          return handleUnfollow(event)
+    case 'user_click_button': return handleButtonClick(event)
+    default: console.warn('Unhandled Zalo event:', event.event_name)
+  }
+}
+
+serve({ fetch: app.fetch, port: 3000 })
+```
+
+**Express**
+
+```typescript
+import express from 'express'
+
+const app = express()
+
+// MUST use raw body parser — not express.json() — to preserve signature input
+app.post('/webhook/zalo', express.raw({ type: 'application/json' }), async (req, res) => {
+  const signature = req.headers['x-zevent-signature'] as string ?? ''
+  const body = req.body.toString()
+
+  if (!verifyWebhookSignature(body, signature, OA_SECRET_KEY)) {
+    return res.status(403).json({ error: 'Invalid signature' })
+  }
+
+  const event: ZaloEvent = JSON.parse(body)
+  res.json({ received: true }) // respond first
+  idempotentHandle(event).catch(console.error) // then process
+})
+```
+
+**Fastify**
+
+```typescript
+import Fastify from 'fastify'
+
+const fastify = Fastify()
+
+fastify.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {
+  done(null, body) // keep raw string for signature verification
+})
+
+fastify.post('/webhook/zalo', async (request, reply) => {
+  const signature = request.headers['x-zevent-signature'] as string ?? ''
+  const body = request.body as string
+
+  if (!verifyWebhookSignature(body, signature, OA_SECRET_KEY)) {
+    return reply.status(403).send({ error: 'Invalid signature' })
+  }
+
+  const event: ZaloEvent = JSON.parse(body)
+  reply.send({ received: true })
+  idempotentHandle(event).catch(console.error)
+})
+```
+
+#### Local Development Tunnel
+
+```bash
+# ngrok (most common)
+ngrok http 3000
+# → copy https://xxxx.ngrok.io → paste to Zalo Developer Portal
+
+# cloudflared (free, no account needed for temp tunnels)
+cloudflare tunnel --url http://localhost:3000
+```
+
+Update webhook URL in Zalo portal every time the tunnel restarts. Use a stable subdomain (`ngrok http --subdomain=myapp 3000`) with a paid ngrok account to avoid this.
+
+#### Sharp Edges
+
+- **5-second timeout**: If your handler takes longer, Zalo marks it failed and retries. Always return 200 immediately, process async.
+- **Wrong secret key**: Signature uses **OA Secret Key** from OA Management → Settings, NOT the App Secret Key from Developer Portal. Different keys, same name confusion.
+- **Raw body required**: Parse body as raw string before verification. Using `express.json()` or Hono's `.json()` before verification will break the HMAC because the body gets re-serialized.
+- **Inconsistent event naming**: `user_send_text` but just `follow` — not `user_follow`. Handle both patterns in your router.
+- **HTTPS required**: Zalo rejects plain HTTP webhook URLs. ngrok/cloudflared tunnels provide HTTPS automatically.
+- **msg_id deduplication is mandatory in production**: Zalo retries on non-200 (up to 3x), and network issues can cause duplicate deliveries. A Redis-backed `SETNX msg_id EX 86400` is the production-safe pattern.

package/extensions/zalo/skills/zalo-personal-messaging.md

@@ -0,0 +1,194 @@
+---
+name: zalo-personal-messaging
+pack: "@rune/zalo"
+description: Personal and group messaging via zca-js — text, media, reactions, group management, mention gating, message buffer for context. UNOFFICIAL — risk-gated.
+model: sonnet
+tools: "Read, Glob, Grep, Bash, Write, Edit"
+---
+
+# zalo-personal-messaging
+
+> ⚠️ Track B (unofficial). See zalo-personal-setup for full risk disclaimer.
+> This skill assumes you have completed zalo-personal-setup and have an active API instance.
+
+## Overview
+
+Send messages, media, and reactions to Zalo personal accounts and groups via zca-js. Covers 1:1 DMs, group messaging, mention-gated bot patterns, and context buffering.
+
+---
+
+## Direct Messages (1:1)
+
+```typescript
+// Send text
+await api.sendMessage('Hello!', threadId, 'User')
+
+// Send image (local file path — download first if URL)
+await api.sendMessage({
+  body: 'Check this image',
+  attachments: [imagePath]
+}, threadId, 'User')
+
+// Chunk long messages (2000-char limit applies to DMs too)
+async function sendLong(text: string, threadId: string, type: 'User' | 'Group') {
+  const chunks = text.match(/.{1,1900}/gs) ?? [text]
+  for (const chunk of chunks) {
+    await api.sendMessage(chunk, threadId, type)
+  }
+}
+```
+
+---
+
+## Group Messaging
+
+```typescript
+// Send to group
+await api.sendMessage('Hello group!', groupId, 'Group')
+
+// Send with mention
+await api.sendMessage({
+  body: '@John check this',
+  mentions: [{ pos: 0, len: 5, uid: johnUserId }]
+}, groupId, 'Group')
+
+// Group management
+await api.createGroup('Bot Test Group', [userId1, userId2]) // min 3 members incl. self
+await api.addGroupMembers(groupId, [newMemberId])
+await api.removeGroupMembers(groupId, [memberId])
+await api.changeGroupName(groupId, 'New Name')
+```
+
+---
+
+## Media Types
+
+| Type | Notes |
+|------|-------|
+| Text | 2000-char limit — chunk if needed |
+| Image | Local file path only — download URL first |
+| Video | Local file path |
+| Voice | Local file path |
+| Sticker | By sticker ID — IDs undocumented, capture from received msgs |
+| File | Local file path |
+| Contact card | User ID reference |
+| Link | Auto-generates preview |
+
+---
+
+## Reactions
+
+```typescript
+// React to a message (11 types)
+await api.sendReaction(messageId, threadId, '❤️', 'User')
+
+// Available: ❤️ 😆 😮 😢 😠 👍 👎 ✊ 🎉 😏 🥰
+```
+
+---
+
+## Mention Gating Pattern
+
+For group bots — only process when @mentioned, buffer other messages for context:
+
+```typescript
+function isMentioned(msg: GroupMessage, botId: string): boolean {
+  return msg.data.mentions?.some(m => m.uid === botId) ?? false
+}
+
+listener.on('group_message', async (msg) => {
+  if (!isMentioned(msg, BOT_USER_ID)) {
+    messageBuffer.push(msg) // buffer for context
+    return
+  }
+  // Bot was mentioned — process with buffered context
+  const context = messageBuffer.getRecent(msg.threadId, 20)
+  const response = await processWithContext(msg, context)
+  await api.sendMessage(response, msg.threadId, 'Group')
+})
+```
+
+> Use `msg.data.mentions` array — never parse `@` from message text (unreliable).
+
+---
+
+## Message Buffer
+
+Buffer recent group messages per thread for context injection:
+
+```typescript
+class MessageBuffer {
+  private buffer: Map<string, Message[]> = new Map()
+  private maxPerThread = 50
+
+  push(msg: Message) {
+    const threadId = msg.threadId
+    const msgs = this.buffer.get(threadId) ?? []
+    msgs.push(msg)
+    if (msgs.length > this.maxPerThread) msgs.shift() // cap to avoid unbounded growth
+    this.buffer.set(threadId, msgs)
+  }
+
+  getRecent(threadId: string, count: number): Message[] {
+    return (this.buffer.get(threadId) ?? []).slice(-count)
+  }
+}
+```
+
+---
+
+## Name Cache
+
+Resolve user IDs to display names with TTL to avoid API hammering:
+
+```typescript
+class NameCache {
+  private cache = new Map<string, { name: string; expiresAt: number }>()
+  private ttl = 60 * 60 * 1000 // 1 hour
+
+  async resolve(userId: string, api: ZaloApi): Promise<string> {
+    const cached = this.cache.get(userId)
+    if (cached && cached.expiresAt > Date.now()) return cached.name
+    try {
+      const profile = await api.getUserInfo(userId)
+      const name = profile.displayName || 'Unknown'
+      this.cache.set(userId, { name, expiresAt: Date.now() + this.ttl })
+      return name
+    } catch {
+      return 'Unknown'
+    }
+  }
+}
+```
+
+---
+
+## Event Listeners
+
+```typescript
+// DM and group events are SEPARATE — wire both
+listener.on('message', async (msg) => {
+  // 1:1 personal messages
+  const senderId = msg.data.uidFrom
+  await handleDM(msg, senderId)
+})
+
+listener.on('group_message', async (msg) => {
+  // Group messages — includes mention data
+  const senderId = msg.data.uidFrom
+  await handleGroup(msg, senderId)
+})
+```
+
+---
+
+## Sharp Edges
+
+- **Separate events**: `message` (DM) vs `group_message` (group) — missing one = silent drop
+- **Mention detection**: check `msg.data.mentions` array, not text `@` parsing
+- **2000-char limit**: applies to both DM and group — always chunk
+- **Image upload**: local file path only — download remote URLs before sending
+- **Sticker IDs**: undocumented — sniff from received sticker messages to build your own map
+- **Group create**: minimum 3 members including self — 2-member call throws
+- **Buffer cap**: always set `maxPerThread` — unbounded growth crashes long-running bots
+- **Name cache TTL**: don't skip — `getUserInfo` rate-limited aggressively on personal accounts

package/extensions/zalo/skills/zalo-personal-setup.md

@@ -0,0 +1,153 @@
+---
+name: zalo-personal-setup
+pack: "@rune/zalo"
+description: Personal Zalo account automation setup via zca-js — QR login, credential persistence, WebSocket listener, session management. UNOFFICIAL — risk-gated.
+model: sonnet
+tools: "Read, Glob, Grep, Bash, Write, Edit"
+---
+
+# zalo-personal-setup
+
+## Purpose
+
+Bootstrap a personal Zalo account automation using zca-js — the community-maintained reverse-engineered client. Handles first-time QR login, credential persistence, WebSocket listener setup, and session restore on subsequent runs.
+
+<HARD-GATE>
+This skill uses UNOFFICIAL reverse-engineered APIs via zca-js.
+BEFORE proceeding, acknowledge ALL risks:
+1. ToS VIOLATION — Zalo can ban your account without warning
+2. SINGLE SESSION — cannot use Zalo mobile/web simultaneously
+3. API INSTABILITY — Zalo can break internal APIs anytime
+4. NO SUPPORT — Zalo will not help with issues from unofficial usage
+5. NOT FOR PRODUCTION — personal projects and prototypes ONLY
+
+If building for business/production → use Track A (zalo-oa-setup) instead.
+</HARD-GATE>
+
+## Step 1 — Install Dependency
+
+```bash
+npm install zca-js
+# zca-js: https://github.com/RFS-ADRENO/zca-js (359★, 202 forks)
+```
+
+Minimum Node.js: 18+. TypeScript users add `@types/node` if not already present.
+
+## Step 2 — QR Login (First Run)
+
+```typescript
+import { Zalo } from 'zca-js'
+
+const zalo = new Zalo()
+
+// First-time login: QR code
+const api = await zalo.loginQR()
+// Terminal displays QR → scan with Zalo mobile app
+// Returns API instance with full access
+
+// Save credentials for next time
+const credentials = {
+  imei: api.getImei(),         // generated device ID
+  cookie: api.getCookie(),      // session cookies
+  userAgent: api.getUserAgent() // browser fingerprint
+}
+await saveCredentials(credentials)
+```
+
+QR code expires in ~60 seconds — scan quickly. After scan, zca-js completes handshake and returns a live API instance.
+
+## Step 3 — Credential Persistence
+
+```typescript
+import { readFile, writeFile, chmod } from 'fs/promises'
+import { join } from 'path'
+import { homedir } from 'os'
+
+const CRED_PATH = join(homedir(), '.zalo-personal', 'credentials.json')
+
+async function saveCredentials(creds: ZaloCredentials): Promise<void> {
+  await writeFile(CRED_PATH, JSON.stringify(creds, null, 2))
+  await chmod(CRED_PATH, 0o600) // owner-only read/write
+}
+
+async function loadCredentials(): Promise<ZaloCredentials | null> {
+  try {
+    return JSON.parse(await readFile(CRED_PATH, 'utf-8'))
+  } catch { return null }
+}
+```
+
+Store at `~/.zalo-personal/credentials.json` — outside the project repo. Never commit credentials to git. Add `.zalo-personal/` to `.gitignore`.
+
+## Step 4 — Session Restore (Subsequent Runs)
+
+```typescript
+const creds = await loadCredentials()
+
+const api = creds
+  ? await zalo.login({
+      imei: creds.imei,
+      cookie: creds.cookie,
+      userAgent: creds.userAgent
+    })
+  : await zalo.loginQR() // fall back to QR if no saved creds
+
+// Always re-persist after login — cookies may have refreshed
+await saveCredentials({
+  imei: api.getImei(),
+  cookie: api.getCookie(),
+  userAgent: api.getUserAgent()
+})
+```
+
+## Step 5 — WebSocket Listener
+
+```typescript
+const listener = api.listener
+await listener.start({ retryOnClose: true })
+
+listener.on('message', (msg) => {
+  // Handle incoming DMs
+  console.log(`[DM] ${msg.data.content}`)
+})
+
+listener.on('group_message', (msg) => {
+  // Group messages arrive on separate event
+  console.log(`[Group] ${msg.data.content}`)
+})
+
+// keepAlive is automatic via zca-js — no manual ping needed
+```
+
+`retryOnClose: true` enables automatic reconnect using the retry schedule provided by Zalo's server.
+
+## Session Management Notes
+
+| Concept | Detail |
+|---------|--------|
+| IMEI | Deterministic UUID from userAgent — acts as device fingerprint. Must stay consistent across restarts. |
+| Cookies | Auto-refreshed on keepAlive. Always re-persist after each session start. |
+| DuplicateConnection (3000) | Another session opened — this one closes. Cannot run bot + Zalo mobile simultaneously. |
+| Reconnect | Handled by zca-js via server retry schedule. No manual logic needed. |
+
+## Anti-Detection Baseline
+
+- Use consistent `userAgent` across sessions — don't randomize on each run
+- Don't send messages too fast (see `zalo-rate-guard` for throttle patterns)
+- Avoid running during unusual hours (3–6 AM local time)
+- Keep sessions long-lived — frequent login/logout is suspicious
+- Never change profile info programmatically
+
+## Sharp Edges
+
+- Cookie refresh happens on keepAlive — **MUST** persist updated cookies after every session start, not just first login
+- IMEI must stay consistent — changing it looks like a new device to Zalo's backend
+- If Zalo mobile is active on same account, bot receives `DuplicateConnection` kick immediately
+- zca-js depends on Zalo's internal undocumented API — breaks without warning on Zalo updates
+- No official rate limits documented — err heavily on the side of caution
+
+## Mesh Links
+
+- `zalo-oa-setup` — Track A (official OA API) if this use case grows to production
+- `zalo-rate-guard` — rate limiting and message throttle for personal bots
+- `zalo-personal-messaging` — send/reply DMs and group messages once session is live