@partme.ai/openclaw-web-stomp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PartMe-AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+<div align="center">
+
+# OpenClaw Web STOMP
+
+**OpenClaw plugin — STOMP 1.x over WebSocket (`stomp-ws`) with topic bindings and `session.dmScope` isolation**
+
+![npm](https://img.shields.io/badge/npm-@partme.ai%2Fopenclaw__web__stomp-blue)
+![Node](https://img.shields.io/badge/Node.js-22+-green)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+</div>
+
+[English](./README.md) | [简体中文](./README_CN.md)
+
+## Introduction
+
+`@partme.ai/openclaw-web-stomp` is an [OpenClaw](https://github.com/openclaw/openclaw) **channel plugin** that exposes **STOMP over WebSocket** and bridges browser or Spring-style clients to agents. It follows the official channel pattern: [`defineChannelPluginEntry`](https://docs.openclaw.ai/plugins/sdk-entrypoints#definechannelpluginentry) and `ChannelPlugin` (not `definePluginEntry`).
+
+Behavior is aligned with **`openclaw-mqtt`**, **`openclaw-web-mqtt`**, and **`openclaw-stomp` (TCP)**:
+
+- **`subscribeTopics`** — inbound **SEND** (and optional **SUBSCRIBE**) allowlist using `*` / `#` patterns on full STOMP destinations.
+- **`topicBindings`** — explicit `topicPattern → agentId` (+ optional `accountId`, `replyTopic` as reply destination).
+- **Standard fallback** — destinations matching `agent.<id>` under `/queue/` (same idea as TCP STOMP plugin).
+- **Session keys** — only from OpenClaw global **`session.dmScope`** via shared `buildSessionKeyFromDmScope` (no channel-local duplicate scope config).
+
+## Capabilities
+
+- **Gateway lifecycle** — server starts in `gateway.startAccount`, stops on abort (same model as `openclaw-web-mqtt`).
+- **Status HTTP** — `GET /stomp-ws/status` (`auth: plugin`) — connections, subscription stats, ACK stats, redacted config snapshot.
+- **Enterprise-style controls** — max connections, max frame / payload size, optional TLS (HTTPS server + WS upgrade), per-user `publishAllow` / `subscribeAllow` / `aclRules` (RabbitMQ-style topic ACL inspiration; see also [Web MQTT](https://www.rabbitmq.com/docs/web-mqtt) operational patterns).
+- **`openclaw.setupEntry`** — `dist/setup-entry.js` for setup-only loads ([SDK setup](https://docs.openclaw.ai/plugins/sdk-setup)).
+
+## Message flow
+
+1. Client **CONNECT** (optional `login` / `passcode` per `channels["stomp-ws"].auth`).
+2. Client **SUBSCRIBE** to `/topic/session.<sessionKey>` (or your policy-approved destinations).
+3. Client **SEND** to a destination allowed by `subscribeTopics`.
+4. Plugin resolves **agent** via `topicBindings` first, then standard agent destination fallback.
+5. OpenClaw **`dispatchReplyFromConfig`** runs; replies publish to `replyTopic` or `/topic/session.<sessionKey>` derived from `dmScope`.
+
+## Quick start
+
+### Prerequisites
+
+- OpenClaw `>= 2026.4.0`
+- Node.js `22+`
+
+### Install
+
+```bash
+openclaw plugins install @partme.ai/openclaw-web-stomp
+```
+
+### Minimal `openclaw.json`
+
+```json
+{
+  "session": {
+    "dmScope": "per-channel-peer"
+  },
+  "channels": {
+    "stomp-ws": {
+      "wsPort": 15674,
+      "path": "/ws",
+      "subscribeTopics": ["/queue/devices/+/in", "/queue/agent.*"],
+      "topicBindings": [
+        {
+          "topicPattern": "/queue/devices/*/in",
+          "agentId": "iot-agent",
+          "accountId": "default",
+          "replyTopic": "/topic/devices/reply"
+        }
+      ],
+      "auth": {
+        "required": false,
+        "allowAnonymous": true
+      }
+    }
+  }
+}
+```
+
+**Migration from legacy `channels.stomp`:** use **`channels["stomp-ws"]`** and channel id **`stomp-ws`**. Legacy keys under `channels.stomp` are merged for convenience but **`stomp-ws` overrides** on conflict.
+
+## Session and `dmScope`
+
+Session isolation uses **only** the OpenClaw root key **`session.dmScope`** (same as `mqtt`, `mqtt-ws`, `stomp-tcp`). Allowed values: `main`, `per-peer`, `per-channel-peer`, `per-account-channel-peer`.
+
+- The plugin **does not** read a channel-local `session.dmScope` under `channels["stomp-ws"]` for isolation (if present elsewhere, it is ignored for this purpose).
+- Inbound `from` is the STOMP **peer id** (headers `x-peer-id` / `peer-id` / `sender`, else login / `client-id` / connection id).
+- Replies go to `topicBindings[].replyTopic` when set, otherwise **`/topic/session.<sessionKey>`** where `sessionKey` is from `buildSessionKeyFromDmScope` with `channel: "stomp-ws"`.
+
+Match **`mqtt-ws` / `stomp-tcp`** docs for how each `dmScope` affects the session key string.
+
+## Security
+
+- **Production:** set `auth.required: true`, disable `allowAnonymous`, and use `auth.users` (plain `password` in config today — prefer env-backed secret injection or a reverse proxy for credential handling).
+- **ACL:** optional `publishAllow`, `subscribeAllow`, and `aclRules` per user (same semantics as `openclaw-web-mqtt`).
+- **TLS:** `tls.enabled` with `certFile` / `keyFile` starts HTTPS and attaches the WebSocket server; alternatively terminate TLS at your edge and proxy to plain `ws` internally.
+- **Limits:** tune `maxConnections`, `limits.maxPayloadBytes`, `maxFrameSize`, and `limits.maxSubscriptionsPerClient` to match broker-style hardening (see [RabbitMQ Web MQTT](https://www.rabbitmq.com/docs/web-mqtt) for operational parallels).
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| CONNECT fails with `Authentication failed` | `auth.users` / `defaultUser`+`defaultPass`, or set `allowAnonymous: true` for dev. |
+| SEND accepted but no agent reply | Gateway running, agent route for `stomp-ws`, `topicBindings` / fallback agent id, and client **SUBSCRIBE** to the actual reply destination (often `/topic/session.<sessionKey>`). |
+| SUBSCRIBE ignored | If `subscribeTopics` is non-empty, destination must match a pattern; check `maxSubscriptionsPerClient`. |
+| `test:client` timeout | Wrong `STOMP_SUBSCRIBE_DESTINATION` for current `session.dmScope`; inspect `GET /stomp-ws/status` and logs. |
+
+## Testing
+
+```bash
+pnpm test
+pnpm run test:client
+```
+
+Test client env vars: `STOMP_WS_URL`, `STOMP_LOGIN`, `STOMP_PASSCODE`, `STOMP_SEND_DESTINATION`, `STOMP_SUBSCRIBE_DESTINATION`, `STOMP_PAYLOAD`, `STOMP_TIMEOUT_MS`.
+
+## GitHub Actions
+
+| Workflow | Trigger | Purpose |
+| --- | --- | --- |
+| [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) | Push / PR `main` / `master` | pnpm install, typecheck, build, test, artifact `dist/` |
+| [`.github/workflows/release.yml`](./.github/workflows/release.yml) | Tag `v*` / `workflow_dispatch` | Publish npm + GitHub Packages, GitHub Release |
+
+## Publishing
+
+- Package: `@partme.ai/openclaw-web-stomp`
+- Secret: `NPM_TOKEN`
+- Details: [`RELEASING.md`](./RELEASING.md)
+
+## Project layout
+
+```text
+src/
+  index.ts           # defineChannelPluginEntry + registerFull
+  setup-entry.ts     # defineSetupPluginEntry
+  channel.ts         # ChannelPlugin + gateway.startAccount
+  stomp-server.ts    # WS + STOMP frame handling
+  stomp-config.ts    # resolve channels["stomp-ws"]
+  inbound.ts         # dispatchReplyFromConfig + dmScope session key
+  dm-scope.ts        # same logic as stomp-tcp / web-mqtt
+  route-inbound.ts   # topicBindings + fallback
+  topic-router.ts    # * / # matching
+  acl.ts             # optional per-user destination ACL
+  outbound.ts        # publish to /topic/session.<key>
+```
+
+## References
+
+- [Building plugins](https://docs.openclaw.ai/plugins/building-plugins)
+- [Channel plugins](https://docs.openclaw.ai/plugins/sdk-channel-plugins)
+- [SDK entrypoints](https://docs.openclaw.ai/plugins/sdk-entrypoints)
+- [Manifest](https://docs.openclaw.ai/plugins/manifest)

package/README_CN.md

@@ -0,0 +1,137 @@
+<div align="center">
+
+# OpenClaw Web STOMP
+
+**OpenClaw 渠道插件 — WebSocket 上的 STOMP（`stomp-ws`），支持 topic 绑定与 `session.dmScope` 会话隔离**
+
+![npm](https://img.shields.io/badge/npm-@partme.ai%2Fopenclaw__web__stomp-blue)
+![Node](https://img.shields.io/badge/Node.js-22+-green)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+</div>
+
+[English](./README.md) | [简体中文](./README_CN.md)
+
+## 简介
+
+`@partme.ai/openclaw-web-stomp` 为 [OpenClaw](https://github.com/openclaw/openclaw) 提供 **STOMP over WebSocket** 渠道，便于浏览器、Spring 等客户端接入 Agent。实现上使用官方推荐的 [`defineChannelPluginEntry`](https://docs.openclaw.ai/plugins/sdk-entrypoints#definechannelpluginentry) 与 `ChannelPlugin`（**不要**用仅适用于非渠道的 `definePluginEntry`）。
+
+路由与 **`openclaw-mqtt` / `openclaw-web-mqtt` / `openclaw-stomp`（TCP）** 保持一致：
+
+- **`subscribeTopics`**：对 **SEND** 的 destination 做白名单（`SUBSCRIBE` 在非空时同样校验）；支持 `*`、`#`。
+- **`topicBindings`**：`topicPattern` → `agentId`，可选 `accountId`、`replyTopic`（回复 STOMP destination）。
+- **标准回退**：与 TCP 版相同的 `agent.<id>` destination 解析。
+- **会话键**：仅使用 OpenClaw 全局 **`session.dmScope`** 与 `buildSessionKeyFromDmScope`，**不**维护渠道私有隔离配置。
+
+## 能力概览
+
+- **网关生命周期**：在 `gateway.startAccount` 内启动 HTTP(S)+WS，abort 时停止（与 `openclaw-web-mqtt` 一致）。
+- **状态接口**：`GET /stomp-ws/status`（`auth: plugin`）返回连接、订阅、ACK 统计与脱敏配置。
+- **企业向控制**：连接数、帧/载荷上限、可选 TLS、用户级 `publishAllow` / `subscribeAllow` / `aclRules`（思路参考 RabbitMQ [Web MQTT](https://www.rabbitmq.com/docs/web-mqtt) 的运维与安全实践）。
+- **setup 入口**：`package.json` → `openclaw.setupEntry` → `dist/setup-entry.js`（见 [SDK setup](https://docs.openclaw.ai/plugins/sdk-setup)）。
+
+## 消息流
+
+1. 客户端 **CONNECT**（按 `auth` 校验 `login` / `passcode`）。
+2. **SUBSCRIBE** 到 `/topic/session.<sessionKey>` 等允许的 destination。
+3. **SEND** 到通过 `subscribeTopics` 的 destination。
+4. 插件按 **`topicBindings` 优先**，否则标准 agent destination 回退解析 **agent**。
+5. 调用 OpenClaw **`dispatchReplyFromConfig`**；回复发到绑定 **`replyTopic`** 或按 `dmScope` 生成的 **`/topic/session.<sessionKey>`**。
+
+## 快速开始
+
+### 环境
+
+- OpenClaw `>= 2026.4.0`
+- Node.js `22+`
+
+### 安装
+
+```bash
+openclaw plugins install @partme.ai/openclaw-web-stomp
+```
+
+### 最小配置 `openclaw.json`
+
+```json
+{
+  "session": {
+    "dmScope": "per-channel-peer"
+  },
+  "channels": {
+    "stomp-ws": {
+      "wsPort": 15674,
+      "path": "/ws",
+      "subscribeTopics": ["/queue/devices/+/in"],
+      "topicBindings": [
+        {
+          "topicPattern": "/queue/devices/*/in",
+          "agentId": "iot-agent",
+          "replyTopic": "/topic/devices/reply"
+        }
+      ],
+      "auth": {
+        "required": false,
+        "allowAnonymous": true
+      }
+    }
+  }
+}
+```
+
+**从旧版迁移：** 旧渠道 id `stomp` 与 `channels.stomp` 请改为 **`stomp-ws`** 与 **`channels["stomp-ws"]`**。为兼容过渡期，解析配置时会合并 `channels.stomp`，但 **`stomp-ws` 字段优先**。
+
+## 会话与 `dmScope`
+
+会话隔离**仅**依赖 OpenClaw 根配置 **`session.dmScope`**（与 `mqtt`、`mqtt-ws`、`stomp-tcp` 一致）。合法取值：`main`、`per-peer`、`per-channel-peer`、`per-account-channel-peer`。
+
+- 本插件**不会**使用 `channels["stomp-ws"]` 下的私有 `session.dmScope` 做隔离。
+- 入站 `from` 使用 STOMP **peerId**（帧头 `x-peer-id` / `peer-id` / `sender`，否则为 login / `client-id` / 连接 id）。
+- 回复优先发往 `topicBindings[].replyTopic`；否则为 **`/topic/session.<sessionKey>`**，其中 `sessionKey` 由 `buildSessionKeyFromDmScope`（`channel: stomp-ws`）生成。
+
+各 `dmScope` 档下会话键形态请对照 **`mqtt-ws` / `stomp-tcp`** 文档说明。
+
+## 安全
+
+- **生产环境**：建议 `auth.required: true`、关闭 `allowAnonymous`，使用 `auth.users`；当前实现为配置内明文 `password` 比对，更敏感场景请用环境变量注入或前置代理鉴权。
+- **ACL**：可选 `publishAllow`、`subscribeAllow`、`aclRules`（与 `openclaw-web-mqtt` 同类）。
+- **TLS**：`tls.enabled` 且配置证书时由本插件起 HTTPS 并挂载 WS；也可在边缘终止 TLS 后反代到内网 `ws`。
+- **限额**：按需调整 `maxConnections`、`limits.maxPayloadBytes`、`maxFrameSize`、`limits.maxSubscriptionsPerClient`（运维思路可参考 [RabbitMQ Web MQTT](https://www.rabbitmq.com/docs/web-mqtt)）。
+
+## 排障
+
+| 现象 | 排查 |
+| --- | --- |
+| CONNECT 报认证失败 | 检查 `auth.users` 或 `defaultUser`/`defaultPass`；开发环境可临时 `allowAnonymous: true`。 |
+| SEND 有反应但无 Agent 回复 | 确认 Gateway 已起、路由包含 `stomp-ws`、`topicBindings`/默认 agent；客户端是否 **SUBSCRIBE** 了真实回复 destination（常为 `/topic/session.<sessionKey>`）。 |
+| SUBSCRIBE 无效 | `subscribeTopics` 非空时 destination 必须匹配其一；是否触达 `maxSubscriptionsPerClient`。 |
+| `test:client` 超时 | `STOMP_SUBSCRIBE_DESTINATION` 是否与当前 `session.dmScope` 下 session 一致；查看 `GET /stomp-ws/status` 与日志。 |
+
+## 测试
+
+```bash
+pnpm test
+pnpm run test:client
+```
+
+环境变量见英文 README「Testing」一节。
+
+## GitHub Actions 与发版
+
+| 工作流 | 触发 | 说明 |
+| --- | --- | --- |
+| [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) | push / PR | 安装、类型检查、构建、测试、上传 `dist` |
+| [`.github/workflows/release.yml`](./.github/workflows/release.yml) | 标签 `v*` | 发布 npm 与 GitHub Packages、创建 Release |
+
+发版说明：[`RELEASING.md`](./RELEASING.md)，需配置 Secret **`NPM_TOKEN`**。
+
+## 目录结构
+
+与英文 README「Project layout」一致：`index.ts`、`setup-entry.ts`、`channel.ts`、`stomp-server.ts`、`stomp-config.ts`、`inbound.ts`、`dm-scope.ts`、`route-inbound.ts`、`topic-router.ts`、`acl.ts`、`outbound.ts`。
+
+## 参考链接
+
+- [Building plugins](https://docs.openclaw.ai/plugins/building-plugins)
+- [Channel plugins](https://docs.openclaw.ai/plugins/sdk-channel-plugins)
+- [SDK entrypoints](https://docs.openclaw.ai/plugins/sdk-entrypoints)
+- [Manifest](https://docs.openclaw.ai/plugins/manifest)

package/RELEASING.md

@@ -0,0 +1,77 @@
+# Releasing `@partme.ai/openclaw-web-stomp`
+
+## Prerequisites
+
+- npm package name: `@partme.ai/openclaw-web-stomp`
+- repository secret: `NPM_TOKEN`
+- Node.js 22+ (see `package.json` → `engines`)
+
+## CI (continuous integration)
+
+Workflow: `.github/workflows/ci.yml`
+
+| Trigger | Behavior |
+|---------|----------|
+| **Push** to `main` or `master` | `pnpm install --frozen-lockfile` → typecheck → build → test → upload **`dist/`** artifact |
+| **Pull request** targeting `main` or `master` | Same as push |
+
+## Version tag rule (required for Releases & Packages)
+
+GitHub **Releases** and **Packages** are created only when you push a **git tag**, not a branch.
+
+| Rule | Detail |
+|------|--------|
+| **Format** | `v` + **semver**, same as `package.json` → `version` |
+| **Example** | If `"version": "0.2.0"` in `package.json`, the tag **must** be **`v0.2.0`** |
+| **Not** | A branch name (e.g. `feature/v0.1.0`) does **not** trigger the `publish` job |
+| **Workflow** | `.github/workflows/release.yml` runs the `publish` job only for refs like `refs/tags/v*` |
+
+After pushing `v0.2.0`, Actions publishes to npmjs + GitHub Packages and creates a GitHub Release with the `.tgz`.
+
+## Local release check
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run build
+pnpm test
+```
+
+## Bump version and tag (recommended)
+
+Use pnpm so `package.json` and git tag stay aligned:
+
+```bash
+pnpm version patch   # or minor / major — updates package.json and creates commit + tag vX.Y.Z
+git push origin main --follow-tags
+```
+
+Or set the version manually, then tag **exactly** `v` + that version:
+
+```bash
+# Example: package.json already says "0.2.0"
+git tag -a v0.2.0 -m "v0.2.0"
+git push origin v0.2.0
+```
+
+Release workflow publishes on `v*` tags. npm publish is skipped if that version already exists on npm.
+
+## GitHub Packages (`npm.pkg.github.com`)
+
+GitHub’s npm registry requires the package scope to match the repository owner. The workflow publishes **`@partme.ai/openclaw-web-stomp`** to npmjs, and **`@<github-owner>/openclaw-web-stomp`** (for example **`@partme-ai/openclaw-web-stomp`**) to GitHub Packages. Install from GitHub Packages only when you intentionally use that registry and auth (PAT with `read:packages`).
+
+## Manual publish from GitHub Actions
+
+1. Open **Actions** → **Release**
+2. Click **Run workflow** (this runs the `package` job only; it does **not** publish to npm/GitHub Packages/Release unless the run is from a **`v*`** tag)
+3. For a real publish, push a **`vX.Y.Z`** tag as above, then confirm logs show:
+   - `Published @partme.ai/openclaw-web-stomp@x.y.z` (npmjs)
+   - `Published @<github-owner>/openclaw-web-stomp@x.y.z` (GitHub Packages)
+
+## Common issues
+
+- **No Releases / Packages on GitHub**: No **`v*`** tag has been pushed yet — push `v` + semver matching `package.json`.
+- **`ERR_PNPM_OUTDATED_LOCKFILE`**: Run `pnpm install` locally and commit the updated `pnpm-lock.yaml` whenever `package.json` dependencies change.
+- `npm ERR! 403`: version already published or token permissions insufficient
+- `NPM_TOKEN is not set`: add secret in repo settings
+- `npm whoami` failed: token expired or wrong scope permission