@ramxvnn/bridge 0.1.0

package/runtime/transports/shared/webhook-server.js

@@ -0,0 +1,101 @@
+/**
+ * Minimal HTTP server shared by the webhook transports (Zalo OA, LINE).
+ *
+ * Telegram and Discord reach out; Zalo OA and LINE push in. Those two need an
+ * HTTP endpoint on the operator's own infrastructure — **not** on RAM/X. That
+ * distinction matters enough to repeat in every README: the public callback
+ * URL a platform console asks for points at the machine running this runtime.
+ *
+ * Two details are load-bearing:
+ *
+ *   1. The RAW body is captured and handed to the verifier untouched. Both
+ *      platforms sign the exact bytes they sent; re-serializing parsed JSON
+ *      changes whitespace and breaks verification (LINE's docs are explicit
+ *      that any modification makes a legitimate request indistinguishable from
+ *      a tampered one).
+ *   2. Verification happens BEFORE parsing. An unverified body is attacker
+ *      input, so nothing touches it until the signature holds.
+ */
+import { createServer } from 'node:http';
+import { log, redact } from '../../core/redact.js';
+/** Reads the request body as raw text, refusing anything oversized. */
+export function readRawBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                reject(new Error('Request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+export class WebhookServer {
+    server;
+    options;
+    constructor(options) {
+        this.options = { maxBodyBytes: 1024 * 1024, ...options };
+    }
+    async start() {
+        const { port, path, handler, maxBodyBytes } = this.options;
+        this.server = createServer((req, res) => {
+            void (async () => {
+                try {
+                    // A health path is genuinely useful when this runs behind a proxy.
+                    if (req.method === 'GET' && req.url === '/healthz') {
+                        res.writeHead(200, { 'Content-Type': 'text/plain' });
+                        res.end('ok');
+                        return;
+                    }
+                    const url = (req.url ?? '').split('?')[0];
+                    if (req.method !== 'POST' || url !== path) {
+                        res.writeHead(404, { 'Content-Type': 'text/plain' });
+                        res.end('not found');
+                        return;
+                    }
+                    const rawBody = await readRawBody(req, maxBodyBytes);
+                    const headers = {};
+                    for (const [k, v] of Object.entries(req.headers)) {
+                        if (typeof v === 'string')
+                            headers[k.toLowerCase()] = v;
+                    }
+                    const result = await handler({ rawBody, headers });
+                    res.writeHead(result.status, { 'Content-Type': 'text/plain' });
+                    res.end(result.body ?? '');
+                }
+                catch (err) {
+                    // Never echo the error to the caller: it can carry request detail.
+                    log('error', 'Webhook request failed', { error: redact(err) });
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'text/plain' });
+                        res.end('error');
+                    }
+                }
+            })();
+        });
+        await new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(port, () => {
+                log('info', 'Webhook server listening', { port, path });
+                resolve();
+            });
+        });
+    }
+    /** The bound port. Differs from the configured one when port 0 was used. */
+    address() {
+        const addr = this.server?.address();
+        return addr && typeof addr === 'object' ? addr.port : null;
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        this.server = undefined;
+    }
+}

package/runtime/transports/telegram/index.js

@@ -0,0 +1,150 @@
+/**
+ * Telegram transport — long polling via getUpdates.
+ *
+ * WHY LONG POLLING AND NOT A WEBHOOK
+ * ----------------------------------
+ * Telegram's two delivery mechanisms are mutually exclusive: setting a webhook
+ * makes getUpdates fail, and vice versa. For a reference runtime somebody
+ * clones and runs in five minutes, long polling wins on every axis that
+ * matters — no public HTTPS endpoint, no reverse proxy, no certificate, no
+ * inbound firewall rule — so it behaves identically on a laptop, in Docker and
+ * on a VPS. (Contrast the Zalo OA and LINE adapters, which have no choice:
+ * those platforms only deliver by webhook.)
+ *
+ * Nothing here knows RAM/X exists.
+ */
+import { log, registerSecret, redact } from '../../core/redact.js';
+import { defaultSleep, } from '../../core/types.js';
+/**
+ * Advances the polling offset.
+ *
+ * Telegram redelivers any update whose id is >= the offset we ask for, so the
+ * next offset must be (highest id seen + 1). Getting this wrong is how a
+ * runtime double-posts after a reconnect, which is exactly the failure mode
+ * `/ramx_post` must not have.
+ */
+export function nextOffset(currentOffset, updates) {
+    let highest = currentOffset - 1;
+    for (const u of updates) {
+        if (typeof u.update_id === 'number' && u.update_id > highest)
+            highest = u.update_id;
+    }
+    return highest + 1;
+}
+/** Exponential backoff with a ceiling, so an outage cannot hot-loop. */
+export function backoffMs(consecutiveFailures, baseMs = 1000, maxMs = 60_000) {
+    return Math.min(baseMs * 2 ** Math.max(0, consecutiveFailures - 1), maxMs);
+}
+export class TelegramTransport {
+    name = 'telegram';
+    botToken;
+    apiBase;
+    pollTimeoutSeconds;
+    fetchImpl;
+    sleep;
+    running = false;
+    /** Bounded in tests so the loop terminates; unset means run until stopped. */
+    maxCycles;
+    constructor(config, deps = {}) {
+        this.botToken = config.botToken;
+        this.apiBase = config.apiBase.replace(/\/+$/, '');
+        this.pollTimeoutSeconds = config.pollTimeoutSeconds;
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.maxCycles = deps.maxCycles;
+        registerSecret(this.botToken);
+    }
+    /**
+     * The bot token sits in the URL path, so this string is a secret. It is
+     * never logged: every log path here goes through redact().
+     */
+    url(method) {
+        return `${this.apiBase}/bot${this.botToken}/${method}`;
+    }
+    async call(method, body) {
+        const res = await this.fetchImpl(this.url(method), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            // Longer than Telegram's own long-poll window.
+            signal: AbortSignal.timeout((this.pollTimeoutSeconds + 15) * 1000),
+        });
+        const payload = (await res.json().catch(() => ({})));
+        if (!payload.ok) {
+            const err = new Error(`Telegram ${method} failed: ${payload.description ?? `HTTP ${res.status}`}`);
+            err.retryAfterSeconds = payload.parameters?.retry_after;
+            throw err;
+        }
+        return payload.result;
+    }
+    async getUpdates(offset) {
+        return this.call('getUpdates', {
+            offset,
+            timeout: this.pollTimeoutSeconds,
+            allowed_updates: ['message'],
+        });
+    }
+    async sendMessage(chatId, text) {
+        // Telegram rejects messages over 4096 characters outright.
+        const safe = text.length > 4000 ? `${text.slice(0, 3990)}\n…(truncated)` : text;
+        await this.call('sendMessage', {
+            chat_id: chatId,
+            text: safe,
+            disable_web_page_preview: true,
+        });
+    }
+    async getMyUsername() {
+        const me = await this.call('getMe', {});
+        return me.username ?? null;
+    }
+    async start(handler) {
+        this.running = true;
+        let offset = 0;
+        let consecutiveFailures = 0;
+        let cycles = 0;
+        while (this.running && (this.maxCycles === undefined || cycles < this.maxCycles)) {
+            cycles += 1;
+            try {
+                const updates = await this.getUpdates(offset);
+                consecutiveFailures = 0;
+                for (const update of updates) {
+                    const message = update.message;
+                    if (!message?.text)
+                        continue;
+                    try {
+                        await handler({
+                            transport: this.name,
+                            text: message.text,
+                            actorRef: `chat:${message.chat.id}`,
+                            respond: (text) => this.sendMessage(message.chat.id, text),
+                        });
+                    }
+                    catch (err) {
+                        // One bad update must not stall the loop or block the offset.
+                        log('error', 'Failed to handle update', {
+                            update_id: update.update_id,
+                            error: redact(err),
+                        });
+                    }
+                }
+                // Only after the whole batch is processed. A crash mid-batch
+                // redelivers rather than silently skipping.
+                offset = nextOffset(offset, updates);
+            }
+            catch (err) {
+                consecutiveFailures += 1;
+                const hinted = err.retryAfterSeconds;
+                const waitMs = hinted ? hinted * 1000 : backoffMs(consecutiveFailures);
+                log('warn', 'Telegram poll failed; backing off', {
+                    attempt: consecutiveFailures,
+                    waitMs,
+                    error: redact(err),
+                });
+                await this.sleep(waitMs);
+            }
+        }
+    }
+    async stop() {
+        this.running = false;
+    }
+}

package/runtime/transports/zalo-oa/index.js

@@ -0,0 +1,192 @@
+/**
+ * Zalo Official Account transport — signed webhook.
+ *
+ * ⚠ VERIFICATION STATUS — READ BEFORE PRODUCTION USE
+ * ---------------------------------------------------
+ * Unlike the LINE adapter, the signature scheme below could NOT be confirmed
+ * against Zalo's official API reference: developers.zalo.me renders its docs
+ * client-side and does not serve them to a plain fetch. What is implemented
+ * here comes from Zalo's own developer community threads, which consistently
+ * describe:
+ *
+ *   header     X-ZEvent-Signature
+ *   value      "mac=<hex>"
+ *   algorithm  SHA-256 (a plain hash of concatenated values, NOT an HMAC)
+ *   data       appId + <body> + timestamp + OA secret key
+ *
+ * THREE variants appear across those sources, and none is authoritative:
+ *
+ *   A. sha256(appId + body + timestamp + OASecretKey)   <- default
+ *   B. sha256(oaId  + body + timestamp + OASecretKey)
+ *   C. sha256(        body + timestamp + OASecretKey)   <- no id prefix
+ *
+ * plus a second axis: whether `body` is the RAW request bytes or
+ * `JSON.stringify()` of the parsed body.
+ *
+ * All of it is configurable rather than guessed:
+ *
+ *   ZALO_SIGNATURE_ID=<oa id>   -> variant B
+ *   ZALO_SIGNATURE_ID=none      -> variant C
+ *   ZALO_SIGNATURE_BODY=canonical -> re-serialized JSON instead of raw
+ *
+ * Raw is the default because it is the only form that is actually
+ * well-defined; re-serializing changes whitespace and is not byte-stable.
+ *
+ * A wrong choice fails CLOSED — every legitimate webhook is rejected — so this
+ * cannot silently accept forgeries. But it does mean the adapter must be
+ * validated against a real OA before anyone relies on it. See the README.
+ *
+ * The callback URL configured in the Zalo App console points at the machine
+ * running THIS process. It is not a RAM/X endpoint, and RAM/X never sees the
+ * OA secret key or access token.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { log, registerSecret, redact } from '../../core/redact.js';
+import { WebhookServer } from '../shared/webhook-server.js';
+/** Text-bearing user events. Delivery receipts and the like are ignored. */
+export const ZALO_TEXT_EVENTS = ['user_send_text'];
+/**
+ * Computes the expected MAC. Exported so the tests can pin the exact
+ * concatenation order rather than asserting only pass/fail.
+ */
+export function computeZaloMac(signatureId, body, timestamp, oaSecretKey) {
+    return createHash('sha256')
+        .update(`${signatureId}${body}${timestamp}${oaSecretKey}`, 'utf8')
+        .digest('hex');
+}
+export function verifyZaloSignature(input) {
+    const { rawBody, signatureId, oaSecretKey, received } = input;
+    if (!received)
+        return false;
+    // The header is documented as "mac=<hex>"; tolerate a bare hex value too.
+    const presented = received.startsWith('mac=') ? received.slice(4) : received;
+    if (!/^[0-9a-f]{64}$/i.test(presented))
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        return false;
+    }
+    // The timestamp is taken from the signed body itself, so it cannot be
+    // swapped independently of the signature.
+    const timestamp = parsed.timestamp === undefined ? '' : String(parsed.timestamp);
+    if (!timestamp)
+        return false;
+    const body = input.bodyMode === 'canonical' ? JSON.stringify(parsed) : rawBody;
+    const expected = computeZaloMac(signatureId, body, timestamp, oaSecretKey);
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(presented.toLowerCase(), 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+export function isZaloTextEvent(event) {
+    return (typeof event.event_name === 'string' &&
+        ZALO_TEXT_EVENTS.includes(event.event_name) &&
+        typeof event.message?.text === 'string' &&
+        event.message.text.length > 0);
+}
+export class ZaloOaTransport {
+    name = 'zalo_oa';
+    config;
+    signatureId;
+    bodyMode;
+    fetchImpl;
+    server;
+    resolveStopped;
+    constructor(config, deps = {}) {
+        this.config = config;
+        // 'none' selects variant C (no id prefix). An empty string would be
+        // ambiguous with "unset", so the sentinel is explicit.
+        this.signatureId =
+            deps.signatureId === 'none' ? '' : (deps.signatureId ?? config.appId);
+        this.bodyMode = deps.bodyMode ?? 'raw';
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+        registerSecret(config.oaSecretKey);
+        registerSecret(config.accessToken);
+    }
+    /** Sends a message to a user. The access token goes in a header, never a URL. */
+    async sendText(userId, text) {
+        const res = await this.fetchImpl(`${this.config.apiBase.replace(/\/+$/, '')}/message/cs`, {
+            method: 'POST',
+            headers: {
+                access_token: this.config.accessToken,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ recipient: { user_id: userId }, message: { text } }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            throw new Error(`Zalo OA send failed with HTTP ${res.status}`);
+        }
+        // Zalo reports application errors in the body with HTTP 200.
+        const payload = (await res.json().catch(() => ({})));
+        if (typeof payload.error === 'number' && payload.error !== 0) {
+            throw new Error(`Zalo OA send returned error ${payload.error}`);
+        }
+    }
+    /** Processes one webhook delivery. Exposed for tests. */
+    async handleWebhook(rawBody, headers, handler) {
+        const verified = verifyZaloSignature({
+            rawBody,
+            signatureId: this.signatureId,
+            oaSecretKey: this.config.oaSecretKey,
+            received: headers['x-zevent-signature'],
+            bodyMode: this.bodyMode,
+        });
+        if (!verified) {
+            log('warn', 'Rejected Zalo OA webhook with an invalid signature');
+            return { status: 401, body: 'invalid signature' };
+        }
+        let event;
+        try {
+            event = JSON.parse(rawBody);
+        }
+        catch {
+            return { status: 400, body: 'invalid json' };
+        }
+        if (!isZaloTextEvent(event)) {
+            // Not an error — Zalo sends many event types this runtime ignores.
+            return { status: 200, body: 'ignored' };
+        }
+        const senderId = event.sender?.id;
+        try {
+            await handler({
+                transport: this.name,
+                text: event.message.text,
+                actorRef: `zalo:${senderId ?? 'unknown'}`,
+                respond: async (text) => {
+                    if (!senderId)
+                        return;
+                    await this.sendText(senderId, text);
+                },
+            });
+        }
+        catch (err) {
+            log('error', 'Failed to handle Zalo OA event', { error: redact(err) });
+        }
+        return { status: 200, body: 'ok' };
+    }
+    async start(handler) {
+        this.server = new WebhookServer({
+            port: this.config.webhookPort,
+            path: this.config.webhookPath,
+            handler: (req) => this.handleWebhook(req.rawBody, req.headers, handler),
+        });
+        await this.server.start();
+        log('info', 'Zalo OA transport ready (signed webhook)', {
+            path: this.config.webhookPath,
+            port: this.config.webhookPort,
+            signatureBodyMode: this.bodyMode,
+        });
+        await new Promise((resolve) => {
+            this.resolveStopped = resolve;
+        });
+    }
+    async stop() {
+        await this.server?.stop();
+        this.resolveStopped?.();
+    }
+}