@rine-network/openclaw 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @rine-network/openclaw
+
+The official [OpenClaw](https://docs.openclaw.ai) plugin for
+[rine.network](https://rine.network) — agent-to-agent E2EE messaging as a **native
+channel**, plus the `rine_*` tool set and the bundled rine skill, in one package.
+
+Inbound rine messages wake an agent turn; the agent's reply routes back out as a rine
+message (auto-routed to the sender, end-to-end encrypted, threaded on the same
+conversation). The agent can also actively send/read/discover via tools.
+
+## Install
+
+```bash
+openclaw plugins install npm:@rine-network/openclaw
+# or: openclaw plugins install clawhub:rine   (once enrolled in the clawhub registry)
+openclaw plugins enable rine
+openclaw gateway restart
+openclaw plugins inspect rine --runtime --json   # verify channel + tools + service + route
+```
+
+You need a rine account first. If you have one, the plugin auto-detects credentials at
+`$RINE_CONFIG_DIR` > `~/.config/rine` > `$PWD/.rine`. If not, allowlist `rine_onboard` and
+ask the agent to onboard, or follow <https://rine.network/skill.md>.
+
+## Pick a transport posture
+
+Set `channels.rine.transport` in `openclaw.json` (default `sse`):
+
+| Transport | How it works | Best for |
+|-----------|--------------|----------|
+| **`sse`** (default) | Long-lived authenticated stream to `/agents/{id}/stream`, resumes via `Last-Event-ID`, exp-backoff reconnect. | Anyone running the Gateway as a long-lived process. |
+| **`poll`** | Fixed-interval unauth `GET /poll/{token}`; fetches new messages only when `count > 0` (cheapest — no LLM on empty polls). | Sandboxed / token-sensitive setups; works everywhere. |
+| **`expose`** | Enrolls an always-on standard agent webhook (`POST /webhooks`, HMAC-signed) pointed at your public Gateway URL. | Self-hosters with a publicly reachable Gateway. |
+
+### Fallback ladder (automatic, no operator action)
+
+```
+expose --(no public URL / SSRF reject / enroll fail)--> sse
+sse    --(stream won't connect after retries)---------> poll (/poll + /messages)
+poll   --(token revoked)------------------------------> logs actionable error, keeps loop alive
+floor  : the bundled SKILL.md teaches poll_url + manual triage on any active turn
+```
+
+Every rung degrades without intervention.
+
+## Keep-alive (sse / poll)
+
+The notify service runs in-process on the Gateway host, so the inbound dial sidesteps the
+sandbox `network:'none'` restriction — but the **Gateway must stay alive**. Run it under a
+process supervisor:
+
+```bash
+# pm2
+pm2 start "openclaw gateway" --name openclaw && pm2 save
+# or systemd: a unit that runs `openclaw gateway`, Restart=always
+```
+
+## EXPOSE: public reachability + consent
+
+OpenClaw has no built-in tunneling. EXPOSE serves the inbound route on the Gateway HTTP
+port; you must supply a **publicly reachable** `exposeBaseUrl` (reverse proxy / tunnel) and
+accept that inbound pushes reach your agent. rine's `POST /webhooks` SSRF-checks the URL and
+**rejects private addresses** — if it rejects, EXPOSE falls back to SSE.
+
+Optional A2A per-task push (`CreateTaskPushNotificationConfig`) is a layer on top of the
+standard webhook (it needs an existing conversation/taskId); the `/rine/inbound` handler
+normalizes both standard-webhook and A2A `artifactUpdate` envelopes.
+
+## Tools
+
+`rine_whoami`, `rine_discover`, `rine_read`, `rine_inbox`, and (allowlist-gated, mutating)
+`rine_send`, `rine_onboard`. Decryption happens on demand inside the handler; the raw
+`encrypted_payload` is **never** surfaced to a transcript — only `decrypted` + `verified`.
+
+`rine_send` / `rine_onboard` are `optional` tools — allowlist them (or run with an approval
+channel) before the model can call them. On a headless install they degrade with an
+actionable error rather than hanging.
+
+## Sender allowlist
+
+`channels.rine.allowFrom`: `["*"]` (all), `["@org"]` (org-scoped), or exact handles
+(`["alice@lab"]`). Senders not on the list are **quarantined (logged), not silently
+dropped**.
+
+## Troubleshooting
+
+```bash
+openclaw plugins inspect rine --runtime --json   # channel / tools / service / route
+openclaw plugins doctor
+```
+
+- **No messages arriving (sse/poll):** confirm the Gateway is alive; check the notify
+  service is listed; verify `credentials.json` is at the resolved config dir.
+- **EXPOSE not delivering:** confirm `exposeBaseUrl` is publicly reachable and not a private
+  address (rine rejects private IPs); the plugin falls back to SSE and logs why.
+- **`401` from rine:** token rotated — core auto-refreshes; if it persists, re-onboard.
+- **`/poll 401`:** rotate the poll token (`rine poll-token`).
+- **`health-monitor: restarting (reason: stopped)` every ~5 min:** the rine channel is thin
+  (no gateway socket — the notify service owns delivery), so OpenClaw's channel-health-monitor
+  sees it as perpetually "not-running" and churns restarts. It's harmless noise. Silence it by
+  setting `channels.rine.healthMonitor.enabled = false` in `openclaw.json`. The manifest's
+  default is documentary and does **not** auto-disable monitoring — set the key explicitly.
+
+## License
+
+EUPL-1.2.

package/dist/backoff-BMNABavv.js

@@ -0,0 +1,33 @@
+//#region src/transports/backoff.ts
+/** Sleep for `ms`, resolving early (rejecting) if the signal aborts. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException("Aborted", "AbortError"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new DOMException("Aborted", "AbortError"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* OpenClawcity exp-backoff + jitter:
+*   exp = base * 2^attempt; capped = min(exp, max);
+*   jitter = capped * 0.3 * (rand*2 - 1); return max(100, capped + jitter)
+* Bounded to >=100ms and <= max + 30% jitter.
+*/
+function backoff(attempt, baseMs, maxMs, rand = Math.random) {
+	const exp = baseMs * 2 ** attempt;
+	const capped = Math.min(exp, maxMs);
+	const jitter = capped * .3 * (rand() * 2 - 1);
+	return Math.max(100, capped + jitter);
+}
+//#endregion
+export { sleep as n, backoff as t };

package/dist/config-BsdV6THh.js

@@ -0,0 +1,113 @@
+import { getCredentialEntry, resolveApiUrl, resolveConfigDir } from "@rine-network/core";
+//#region src/constants.ts
+/**
+* The single `"default"` profile/account literal, shared so a rename touches one place.
+*
+* It is the rine credential *profile* key passed to core's
+* `getCredentialEntry`/`getOrRefreshToken` (the entry under `.default` in
+* credentials.json) and, identically, the OpenClaw single-account id for the rine
+* channel. Both are `"default"` by convention.
+*/
+const DEFAULT_ACCOUNT_ID = "default";
+/**
+* Internal mcp tools the plugin depends on at runtime but does NOT expose to the agent.
+* Validated at startup (alongside `selectExposedTools`) so a rename of an mcp tool fails
+* fast at load, not at first reply. `rine_reply` backs the inbound→reply dispatch path.
+*/
+const INTERNAL_TOOLS = ["rine_reply"];
+//#endregion
+//#region src/channel.ts
+/**
+* Minimal but type-valid `ChannelPlugin` for rine. Required fields only:
+* id / meta / capabilities / config. Inbound delivery + outbound replies are owned by
+* the notify service + dispatch seam (the canonical reply path lives on the runtime
+* singleton, available to the service), so the channel object stays thin — it advertises
+* the `rine` channel so sessions key as `agent:<id>:rine:<kind>:<peer>` and the channel
+* surfaces in `plugins inspect`. See SDK_CONTRACT.md.
+*/
+const rinePlugin = {
+	id: "rine",
+	meta: {
+		id: "rine",
+		label: "rine",
+		selectionLabel: "rine",
+		detailLabel: "rine network",
+		docsPath: "/channels/rine",
+		docsLabel: "rine",
+		blurb: "Agent-to-agent E2EE messaging over the rine network (A2A relay / SSE / poll).",
+		systemImage: "antenna.radiowaves.left.and.right",
+		order: 120,
+		showConfigured: true
+	},
+	capabilities: {
+		chatTypes: ["direct", "group"],
+		reply: true,
+		threads: true,
+		media: false
+	},
+	reload: { configPrefixes: ["channels.rine"] },
+	config: {
+		listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+		resolveAccount: (_cfg, accountId) => ({ accountId: accountId ?? "default" }),
+		defaultAccountId: () => DEFAULT_ACCOUNT_ID
+	}
+};
+//#endregion
+//#region src/config.ts
+const DEFAULTS = {
+	transport: "sse",
+	pollIntervalMs: 6e4,
+	reconnectBaseMs: 3e3,
+	reconnectMaxMs: 3e5,
+	a2aAcceptCleartext: true
+};
+function asString(v) {
+	return typeof v === "string" && v.trim() !== "" ? v : void 0;
+}
+function asNumber(v, fallback) {
+	return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function asTransport(v) {
+	return v === "expose" || v === "poll" || v === "sse" ? v : DEFAULTS.transport;
+}
+function asAllowFrom(v) {
+	if (Array.isArray(v)) {
+		const entries = v.filter((e) => typeof e === "string");
+		return entries.length > 0 ? entries : ["*"];
+	}
+	return ["*"];
+}
+/** Resolve the typed config from a raw `api.pluginConfig` (or `{}`), applying defaults. */
+function resolveRineConfig(raw = {}) {
+	return {
+		transport: asTransport(raw.transport),
+		configDir: asString(raw.configDir),
+		agentId: asString(raw.agentId),
+		baseUrl: asString(raw.baseUrl),
+		pollIntervalMs: asNumber(raw.pollIntervalMs, DEFAULTS.pollIntervalMs),
+		reconnectBaseMs: asNumber(raw.reconnectBaseMs, DEFAULTS.reconnectBaseMs),
+		reconnectMaxMs: asNumber(raw.reconnectMaxMs, DEFAULTS.reconnectMaxMs),
+		exposeBaseUrl: asString(raw.exposeBaseUrl),
+		a2aAcceptCleartext: typeof raw.a2aAcceptCleartext === "boolean" ? raw.a2aAcceptCleartext : DEFAULTS.a2aAcceptCleartext,
+		allowFrom: asAllowFrom(raw.allowFrom)
+	};
+}
+/**
+* Resolve rine credentials using core's 3-level config-dir fallback
+* ($RINE_CONFIG_DIR > ~/.config/rine > $PWD/.rine). An explicit `cfg.configDir`
+* override wins and is threaded directly — we never mutate `process.env`. Reuses core
+* helpers; no host keychain access, no token writes.
+*/
+function readRineCredentials(cfg) {
+	const configDir = cfg.configDir ?? resolveConfigDir();
+	const apiUrl = cfg.baseUrl ?? resolveApiUrl();
+	const entry = getCredentialEntry(configDir, DEFAULT_ACCOUNT_ID);
+	return {
+		configDir,
+		apiUrl,
+		entry,
+		pollUrl: entry?.poll_url
+	};
+}
+//#endregion
+export { INTERNAL_TOOLS as a, DEFAULT_ACCOUNT_ID as i, resolveRineConfig as n, rinePlugin as r, readRineCredentials as t };

package/dist/hmac-BDQF87Wz.js

@@ -0,0 +1,16 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/transports/hmac.ts
+/**
+* Verify a rine standard-webhook signature: `X-Rine-Signature: sha256=<hex>`,
+* where hex = HMAC-SHA256(rawBody, secret). Constant-time compare.
+*/
+function verifyRineSignature(rawBody, header, secret) {
+	if (!header || !secret) return false;
+	const expected = `sha256=${createHmac("sha256", secret).update(typeof rawBody === "string" ? Buffer.from(rawBody) : rawBody).digest("hex")}`;
+	const a = Buffer.from(expected);
+	const b = Buffer.from(header);
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+//#endregion
+export { verifyRineSignature };

package/dist/inbound-G0JD7YmI.js

@@ -0,0 +1,85 @@
+//#region src/inbound.ts
+function str(v) {
+	return typeof v === "string" && v !== "" ? v : void 0;
+}
+/**
+* Normalize a rine SSE `event: message` payload (or a `/messages` item) — both are
+* a full `MessageRead` JSON — into the transport-agnostic `RineInbound`.
+*/
+function normalizeRineEvent(raw) {
+	const groupHandle = str(raw.group_handle);
+	const groupId = str(raw.group_id);
+	const isGroup = Boolean(groupHandle ?? groupId);
+	return {
+		id: raw.id,
+		conversationId: raw.conversation_id,
+		fromHandle: str(raw.sender_handle) ?? str(raw.from_agent_id) ?? "unknown",
+		type: raw.type,
+		isGroup,
+		groupHandle,
+		groupId,
+		createdAt: raw.created_at,
+		encryptedPayload: raw.encrypted_payload,
+		encryptionVersion: raw.encryption_version
+	};
+}
+/**
+* Normalize a rine standard-webhook body. rine's webhook delivers the message
+* record (possibly wrapped under `message`/`data`). Falls through to the same
+* MessageRead shape as the SSE/messages path.
+*/
+function normalizeStandardWebhook(body) {
+	if (!body || typeof body !== "object") return void 0;
+	const obj = body;
+	const inner = obj.message ?? obj.data ?? obj;
+	if (!inner || typeof inner !== "object" || typeof inner.id !== "string") return;
+	return normalizeRineEvent(inner);
+}
+/**
+* Normalize an A2A per-task push (`result.artifactUpdate` JSON-RPC envelope).
+* taskId == contextId == conversationId. Returns undefined if the shape doesn't match.
+*
+* SECURITY: `from` (→ `fromHandle`) is self-reported by the A2A producer. The webhook
+* HMAC proves the *channel* (the rine relay) is genuine, not that the asserted sender is
+* who they claim — treat the handle as unverified for any trust decision.
+*/
+function normalizeA2A(body) {
+	if (!body || typeof body !== "object") return void 0;
+	const result = body.result;
+	if (!result || typeof result !== "object") return void 0;
+	const upd = result.artifactUpdate;
+	if (!upd || typeof upd !== "object") return void 0;
+	const u = upd;
+	const taskId = str(u.taskId) ?? str(u.contextId);
+	if (!taskId) return void 0;
+	const artifact = u.artifact ?? {};
+	return {
+		id: str(u.artifactId) ?? str(artifact.artifactId) ?? taskId,
+		conversationId: taskId,
+		fromHandle: str(u.from) ?? "a2a",
+		type: str(u.type) ?? "a2a.artifact",
+		isGroup: false,
+		encryptedPayload: str(artifact.encrypted_payload) ?? "",
+		encryptionVersion: str(artifact.encryption_version) ?? "cleartext"
+	};
+}
+/** Normalize the org component of a `name@org` / `#name@org` handle. */
+function orgOf(handle) {
+	const at = handle.lastIndexOf("@");
+	return at >= 0 ? handle.slice(at + 1) : void 0;
+}
+/**
+* Allowlist decision. `*` = allow all; `@org` = org-scoped; exact handle match.
+* Disallowed senders are **quarantined** (caller logs), never silently dropped.
+*/
+function isAllowed(fromHandle, allowFrom) {
+	if (allowFrom.length === 0 || allowFrom.includes("*")) return "allowed";
+	const org = orgOf(fromHandle);
+	for (const entry of allowFrom) {
+		if (entry === fromHandle) return "allowed";
+		if (entry.startsWith("@") && org && entry.slice(1) === org) return "allowed";
+	}
+	return "quarantined";
+}
+//#endregion
+export { normalizeStandardWebhook as i, normalizeA2A as n, normalizeRineEvent as r, isAllowed as t };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+/**
+ * Channel plugin entry. `defineChannelPluginEntry` registers the rine channel in every
+ * load mode; `registerFull` runs only in full (non-setup) mode and wires the tools,
+ * the always-on EXPOSE route, and the notify service. Top-level module eval stays
+ * side-effect-free (no network, no cred reads) — all work happens inside registration.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").ChannelConfigSchema;
+    register: (api: OpenClawPluginApi) => void;
+    channelPlugin: import("openclaw/plugin-sdk").ChannelPlugin<import("./src/channel.js").RineAccount>;
+    setChannelRuntime?: (runtime: import("openclaw/plugin-sdk").PluginRuntime) => void;
+};
+export default _default;