@mulmobridge/line 0.1.1 → 1.0.1

package/README.md

@@ -62,10 +62,29 @@ Scan the QR code in the LINE Developers Console → Messaging API tab. Send a me
 | `LINE_BRIDGE_DEFAULT_ROLE` | No | Role id to seed new bridge sessions with (e.g. `coder`, `general`). Applied ONLY when a line session first appears — once the user switches role via `/role <id>` the session's own role wins. Unknown role ids silently fall back to the server's default with a warn log. |
 | `BRIDGE_DEFAULT_ROLE` | No | Same as above but shared across every bridge. Transport-specific `LINE_BRIDGE_DEFAULT_ROLE` wins when both are set. |
 
+### Auth token persistence across server restarts
+
+The MulmoClaude server regenerates a fresh bearer token on every startup and writes it to `~/mulmoclaude/.session-token`. The bridge reads that file once at launch and keeps the token in memory — so if the server restarts while the bridge is running, the bridge keeps using the **old** token and every API call returns **401**, silently.
+
+**Fix**: set `MULMOCLAUDE_AUTH_TOKEN` to the same long random value on **both** the server and the bridge. The server uses it verbatim instead of regenerating, so the token survives restarts and the bridge stays authenticated.
+
+```bash
+# Server (one-time setup — same value across restarts)
+MULMOCLAUDE_AUTH_TOKEN=long-random-string yarn dev
+
+# Bridge (separate process / machine — same value)
+MULMOCLAUDE_AUTH_TOKEN=long-random-string \
+  <bridge-specific-envs> \
+  npx <this-package>@latest
+```
+
+Recommended: at least 32 characters of random data (the server logs a warning at startup for shorter values).
+
 ## Notes
 
 - LINE reply tokens expire in **1 minute**. Since Claude responses can take longer, the bridge uses **push messages** instead of reply messages. This requires your bot to be a verified/certified account for push to work with all users, OR the user must have added the bot as a friend first.
 - LINE limits messages to 5 per push call and ~5000 chars per message. Long replies are automatically chunked.
+- **Inbound media** — text and image messages are forwarded to the agent. Image bytes are downloaded via the LINE Data API (`/v2/bot/message/<id>/content`) using the same channel access token; the actual format (JPEG / PNG / HEIC depending on sender) is preserved via the response Content-Type. The photo-EXIF auto-capture flow ([#1222](https://github.com/receptron/mulmoclaude/issues/1222)) writes a sidecar at `data/locations/...` when GPS data is present. Video / audio / file / sticker messages are not forwarded yet.
 
 ## Detailed Setup Guide
 
@@ -114,6 +133,13 @@ Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package famil
 - [`@mulmobridge/xmpp`](https://www.npmjs.com/package/@mulmobridge/xmpp) — XMPP / Jabber
 - [`@mulmobridge/zulip`](https://www.npmjs.com/package/@mulmobridge/zulip) — Zulip
 
+## Related projects
+
+Published from the MulmoClaude monorepo by [Receptron](https://github.com/receptron).
+
+- **[MulmoClaude](https://github.com/receptron/mulmoclaude)** — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
+- **[MulmoTerminal](https://github.com/receptron/mulmoterminal)** — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
+- **[MulmoTerminal manual](https://receptron.github.io/mulmoterminal/)** — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.
 
 ## License
 

package/dist/index.js

@@ -13,22 +13,53 @@
 //   MULMOCLAUDE_API_URL       — default http://localhost:3001
 //   MULMOCLAUDE_AUTH_TOKEN    — bearer token
 import "dotenv/config";
-import crypto from "crypto";
-import express from "express";
-import { createBridgeClient, chunkText } from "@mulmobridge/client";
+import { createBridgeClient, chunkText, formatAckReply } from "@mulmobridge/client";
+import { createWebhookApp, createWebhookRateLimit, verifyHmacSignature } from "@mulmobridge/webhook-runtime";
+import { extractIncomingLineMessage, parseLineWebhookBody } from "./parse.js";
 const TRANSPORT_ID = "line";
 const PORT = Number(process.env.LINE_BRIDGE_PORT) || 3002;
-const channelSecret = process.env.LINE_CHANNEL_SECRET;
-const channelAccessToken = process.env.LINE_CHANNEL_ACCESS_TOKEN;
-if (!channelSecret || !channelAccessToken) {
-    console.error("LINE_CHANNEL_SECRET and LINE_CHANNEL_ACCESS_TOKEN are required.\n" + "See README for setup instructions.");
-    process.exit(1);
+function readRequiredEnv() {
+    const channelSecret = process.env.LINE_CHANNEL_SECRET;
+    const channelAccessToken = process.env.LINE_CHANNEL_ACCESS_TOKEN;
+    if (!channelSecret || !channelAccessToken) {
+        console.error("LINE_CHANNEL_SECRET and LINE_CHANNEL_ACCESS_TOKEN are required.\nSee README for setup instructions.");
+        process.exit(1);
+    }
+    return { channelSecret, channelAccessToken };
 }
+const { channelSecret, channelAccessToken } = readRequiredEnv();
 const client = createBridgeClient({ transportId: TRANSPORT_ID });
 client.onPush((pushEvent) => {
     pushMessage(pushEvent.chatId, pushEvent.message).catch((err) => console.error(`[line] push send failed: ${err}`));
 });
 // ── LINE API helpers ────────────────────────────────────────────
+/** Download an image attached to an inbound LINE message. Returns
+ *  the bytes + Content-Type so the caller can build an Attachment
+ *  envelope for the chat-service socket. Returns null when the
+ *  fetch fails (network error, 4xx, …) — caller logs and skips. */
+async function downloadLineImage(messageId) {
+    try {
+        const res = await fetch(`https://api-data.line.me/v2/bot/message/${encodeURIComponent(messageId)}/content`, {
+            headers: { Authorization: `Bearer ${channelAccessToken}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok) {
+            console.error(`[line] downloadLineImage failed: ${res.status}`);
+            return null;
+        }
+        // LINE returns image/jpeg by default but the Data API also
+        // serves the original sender format (PNG, GIF, …). Trust the
+        // Content-Type header so the photo-EXIF hook (#1222 PR-A) can
+        // tell HEIC apart from JPEG and surface the right sidecar.
+        const mimeType = res.headers.get("content-type")?.split(";")[0].trim() || "image/jpeg";
+        const arrayBuffer = await res.arrayBuffer();
+        return { bytes: Buffer.from(arrayBuffer), mimeType };
+    }
+    catch (err) {
+        console.error(`[line] downloadLineImage network error: ${err}`);
+        return null;
+    }
+}
 async function pushMessage(userId, text) {
     const messages = chunkText(text, 5000).map((messageText) => ({
         type: "text",
@@ -60,50 +91,52 @@ async function pushMessage(userId, text) {
         }
     }
 }
-// ── Signature verification ──────────────────────────────────────
-function verifySignature(body, signature) {
-    const expected = crypto.createHmac("SHA256", channelSecret).update(body).digest("base64");
-    if (expected.length !== signature.length)
-        return false;
-    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
-}
 // ── Webhook server ──────────────────────────────────────────────
-const app = express();
-app.disable("x-powered-by");
-app.use(express.text({ type: "application/json" }));
-app.post("/webhook", async (req, res) => {
+const app = createWebhookApp();
+const webhookRateLimit = createWebhookRateLimit();
+app.post("/webhook", webhookRateLimit, async (req, res) => {
     const signature = req.headers["x-line-signature"];
     const bodyStr = req.body;
-    if (!signature || !verifySignature(bodyStr, signature)) {
+    if (!signature || !verifyHmacSignature(bodyStr, signature, channelSecret)) {
         res.status(401).send("Invalid signature");
         return;
     }
     res.status(200).send("OK");
-    let body;
-    try {
-        body = JSON.parse(bodyStr);
-    }
-    catch {
+    const body = parseLineWebhookBody(bodyStr);
+    if (!body) {
         console.error("[line] malformed JSON in webhook body");
         return;
     }
     for (const event of body.events) {
-        if (event.type !== "message" || event.message?.type !== "text")
-            continue;
-        const userId = event.source?.userId;
-        const text = event.message?.text ?? "";
-        if (!userId || !text.trim())
+        const incoming = extractIncomingLineMessage(event);
+        if (!incoming)
             continue;
-        console.log(`[line] message user=${userId} len=${text.length}`);
         try {
-            const ack = await client.send(userId, text);
-            if (ack.ok) {
-                await pushMessage(userId, ack.reply ?? "");
+            if (incoming.kind === "text") {
+                console.log(`[line] message user=${incoming.userId} len=${incoming.text.length}`);
+                const ack = await client.send(incoming.userId, incoming.text);
+                await pushMessage(incoming.userId, formatAckReply(ack));
+                continue;
             }
-            else {
-                const status = ack.status ? ` (${ack.status})` : "";
-                await pushMessage(userId, `Error${status}: ${ack.error ?? "unknown"}`);
+            // kind === "image"
+            console.log(`[line] image user=${incoming.userId} messageId=${incoming.imageMessageId}`);
+            const image = await downloadLineImage(incoming.imageMessageId);
+            if (!image) {
+                await pushMessage(incoming.userId, "Sorry, I couldn't fetch that image.");
+                continue;
             }
+            // chat-service's `parseMessagePayload` rejects empty `text`
+            // (`text is required`) so attachment-only messages need a
+            // placeholder body. Mirror the Telegram convention (see
+            // `packages/bridges/telegram/src/router.ts`) — an instructive
+            // prompt rather than a caption, so the agent treats the
+            // attachment as the subject and produces a useful response.
+            // The post-save EXIF hook (#1222 PR-A) writes a sidecar if
+            // GPS data is present. (Codex review on PR #1255 / #1263.)
+            const attachments = [{ mimeType: image.mimeType, data: image.bytes.toString("base64") }];
+            const placeholderText = "Describe / analyze this file.";
+            const ack = await client.send(incoming.userId, placeholderText, attachments);
+            await pushMessage(incoming.userId, formatAckReply(ack));
         }
         catch (err) {
             console.error(`[line] message handling failed: ${err}`);

package/dist/parse.d.ts

@@ -0,0 +1,45 @@
+export interface LineMessage {
+    type: string;
+    text?: string;
+    /** LINE content id — present on media types (image / video / audio
+     *  / file). The actual bytes live behind a separate Data API call
+     *  (`/v2/bot/message/<id>/content`); the webhook only carries the
+     *  reference. */
+    id?: string;
+}
+export interface LineEvent {
+    type: string;
+    replyToken?: string;
+    source?: {
+        userId?: string;
+        type?: string;
+    };
+    message?: LineMessage;
+}
+export interface LineWebhookBody {
+    events: LineEvent[];
+}
+/** Discriminated union — the webhook may surface text or media.
+ *  Callers branch on `kind` and either send text straight to chat
+ *  or download the media bytes via the LINE Data API.
+ *
+ *  PR-C of #1222: image is the only media kind we forward today.
+ *  Video / audio / file extend this union if/when they become
+ *  worth fanning out to the agent. */
+export type IncomingLineMessage = {
+    kind: "text";
+    userId: string;
+    text: string;
+} | {
+    kind: "image";
+    userId: string;
+    imageMessageId: string;
+};
+/**
+ * Reduce a LINE webhook event to the actionable shape. Returns null
+ * for non-actionable events (non-message types, missing fields,
+ * unsupported media). Pure — no side effects, no allowlist check.
+ */
+export declare function extractIncomingLineMessage(event: LineEvent): IncomingLineMessage | null;
+/** Best-effort JSON parse for the webhook body — null on malformed input. */
+export declare function parseLineWebhookBody(raw: string): LineWebhookBody | null;

package/dist/parse.js

@@ -0,0 +1,39 @@
+// Pure parsing helpers for the LINE bridge webhook.
+/**
+ * Reduce a LINE webhook event to the actionable shape. Returns null
+ * for non-actionable events (non-message types, missing fields,
+ * unsupported media). Pure — no side effects, no allowlist check.
+ */
+export function extractIncomingLineMessage(event) {
+    if (event.type !== "message")
+        return null;
+    const userId = event.source?.userId;
+    if (!userId)
+        return null;
+    const { message } = event;
+    if (!message)
+        return null;
+    if (message.type === "text") {
+        const text = message.text ?? "";
+        if (!text.trim())
+            return null;
+        return { kind: "text", userId, text };
+    }
+    if (message.type === "image" && typeof message.id === "string" && message.id.length > 0) {
+        return { kind: "image", userId, imageMessageId: message.id };
+    }
+    return null;
+}
+/** Best-effort JSON parse for the webhook body — null on malformed input. */
+export function parseLineWebhookBody(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.events)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/line",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "description": "LINE bridge for MulmoBridge — connect a LINE bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,19 +16,41 @@
     "build": "tsc",
     "prepack": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "echo no tests yet"
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
   },
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^0.1.4",
-    "@mulmobridge/protocol": "^0.1.4",
+    "@mulmobridge/client": "^1.0.1",
+    "@mulmobridge/protocol": "^1.0.1",
+    "@mulmobridge/webhook-runtime": "^1.0.2",
     "dotenv": "^17.0.0",
-    "express": "^5.1.0"
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.6.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/bridges/line#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/receptron/mulmoclaude.git",
+    "directory": "packages/bridges/line"
+  },
+  "keywords": [
+    "line",
+    "line-messaging-api",
+    "mulmobridge",
+    "chatbot",
+    "bridge",
+    "ai-agent",
+    "mulmoclaude"
+  ],
+  "bugs": {
+    "url": "https://github.com/receptron/mulmoclaude/issues"
   }
 }