@securecoms/agent-bridge 0.37.0 → 0.38.0

package/connectors/hermes/tests/test_securecoms_transport.py

@@ -10,9 +10,12 @@
 
 import json
 import os
+import subprocess
+import sys
 
 import pytest
 
+import securecoms_transport
 from securecoms_transport import (
     ChannelStatusManager,
     ResolvedTarget,
@@ -606,3 +609,127 @@ class TestChannelStatusManager:
         clock.advance(100.0)
         await mgr.on_typing("ch1")
         assert all(f["state"] != "idle" for f in send.frames)
+
+
+PNG = b"\x89PNG\r\n\x1a\n\x00\x00\x00\r"
+JPEG = b"\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01"
+GIF = b"GIF89a\x01\x00\x01\x00\x00\x00"
+WEBP = b"RIFF\x10\x00\x00\x00WEBPVP8 "
+
+
+class TestInboundAttachments:
+    @pytest.fixture(autouse=True)
+    def _dir(self, tmp_path):
+        self.root = tmp_path
+        self.dir = tmp_path / "attachments" / "chan"
+        self.dir.mkdir(parents=True)
+
+    def _att(self, name, data=JPEG, mime="image/jpeg", directory=None):
+        d = directory or self.dir
+        d.mkdir(parents=True, exist_ok=True)
+        p = d / f"m-{name}"
+        p.write_bytes(data)
+        return {"filename": name, "mime": mime, "size": len(data), "path": str(p), "sha256": "x"}
+
+    def _frame(self, attachments):
+        return {"type": "message", "channel_id": "chan", "attachments": attachments}
+
+    def test_each_allowed_image_type_passes_with_the_sniffed_lowercase_mime(self):
+        for name, data, mime in [("a.png", PNG, "image/png"), ("b.jpg", JPEG, "image/jpeg"),
+                                 ("c.gif", GIF, "image/gif"), ("d.webp", WEBP, "image/webp")]:
+            a = self._att(name, data, mime.upper())
+            assert securecoms_transport.inbound_attachments(self._frame([a])) == [(a["path"], mime)]
+
+    def test_non_images_mismatches_and_oversize_are_dropped(self):
+        big = PNG + b"\x00" * securecoms_transport.MAX_INBOUND_ATTACHMENT_BYTES
+        bad = [
+            self._att("v.mp3", b"ID3\x04\x00\x00\x00\x00\x00\x00\x00\x00", "audio/mpeg"),
+            self._att("d.pdf", b"%PDF-1.7\n....", "application/pdf"),
+            self._att("x.svg", b"<svg xmlns='http://www.w3.org/2000/svg'><script/></svg>", "image/svg+xml"),
+            self._att("png-as.jpg", PNG, "image/jpeg"),
+            self._att("t.png", b"just some text", "image/png"),
+            self._att("big.png", big, "image/png"),
+        ]
+        for b in bad:
+            assert securecoms_transport.inbound_attachments(self._frame([b])) == [], b["filename"]
+        assert securecoms_transport.scan_inbound_attachments(self._frame(bad)) == ([], len(bad))
+
+    def test_bad_paths_and_names_are_dropped(self):
+        good = self._att("ok.jpg")
+        outside = self._att("id.jpg", directory=self.root / "secrets" / "chan")
+        other = self._att("o.jpg", directory=self.root / "attachments" / "other")
+        bad = [
+            {**good, "path": "relative/attachments/chan/m-ok.jpg"},
+            {**good, "path": f"{self.dir}/../chan/m-ok.jpg"},
+            {**good, "path": f"{self.dir}/./m-ok.jpg"},
+            {**good, "path": f"{self.dir}/"},  # empty basename (normpath strips the "/")
+            {**good, "path": outside["path"]},
+            {**good, "path": other["path"]},
+            {**good, "path": f"{self.dir}/x\0.jpg"},
+            {**good, "path": self._att("rtl‮gpj.jpg")["path"]},
+            {**good, "path": self._att("nl\n.jpg")["path"]},
+            {**good, "filename": "inv‮fdp.jpg"},
+            {**good, "filename": 5},
+            {**good, "path": 42},
+            {**good, "mime": 7},
+            None,
+            "string",
+        ]
+        for b in bad:
+            assert securecoms_transport.inbound_attachments(self._frame([b])) == [], b
+        assert len(securecoms_transport.inbound_attachments(self._frame(bad + [good]))) == 1
+
+    def test_the_basename_guard_alone_rejects_an_empty_basename(self, monkeypatch):
+        # normpath already strips a trailing "/", so neutralize it to prove the
+        # basename guard is a real second check, not dead code.
+        good = self._att("ok.jpg")
+        monkeypatch.setattr(securecoms_transport.os.path, "normpath", lambda p: p)
+        assert securecoms_transport.inbound_attachments(self._frame([{**good, "path": f"{self.dir}/"}])) == []
+
+    def test_guards_only_normpath_or_isabs_catch(self, monkeypatch):
+        # Review r2 mutation survivors: a real image reachable through an
+        # unnormalized path whose literal parent is .../attachments/chan.
+        self._att("f.png", PNG, "image/png", directory=self.root / "y" / "attachments" / "chan")
+        dotted = f"{self.root}/attachments/chan/../../y/attachments/chan/m-f.png"
+        assert securecoms_transport.inbound_attachments(self._frame([{"path": dotted, "mime": "image/png"}])) == []
+        # A relative path that resolves to a real image from the cwd.
+        self._att("rel.png", PNG, "image/png")
+        monkeypatch.chdir(self.root)
+        rel = "attachments/chan/m-rel.png"
+        assert os.path.isfile(rel)
+        assert securecoms_transport.inbound_attachments(self._frame([{"path": rel, "mime": "image/png"}])) == []
+
+    def test_a_fifo_is_dropped_without_hanging(self):
+        # O_NONBLOCK: without it, open() on a FIFO with no writer blocks forever,
+        # so run the scan in a child with a hard timeout.
+        fifo = self.dir / "m-hang.png"
+        os.mkfifo(fifo)
+        frame = {"channel_id": "chan", "attachments": [{"path": str(fifo), "mime": "image/png"}]}
+        script = "import json, sys; import securecoms_transport as t; print(json.dumps(t.scan_inbound_attachments(json.loads(sys.stdin.read()))))"
+        hermes_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        r = subprocess.run([sys.executable, "-c", script], input=json.dumps(frame), capture_output=True, text=True,
+                           timeout=15, cwd=hermes_dir, env={**os.environ, "PYTHONPATH": hermes_dir})
+        assert r.returncode == 0, r.stderr
+        assert json.loads(r.stdout) == [[], 1]
+
+    def test_a_symlink_is_not_followed(self):
+        target = self._att("real.png", PNG, "image/png", directory=self.root / "elsewhere")
+        link = self.dir / "m-link.png"
+        os.symlink(target["path"], link)
+        assert securecoms_transport.inbound_attachments(self._frame([{"path": str(link), "mime": "image/png"}])) == []
+
+    def test_all_attachments_share_one_dir(self):
+        good = self._att("a.jpg")
+        other = self._att("b.jpg", directory=self.root / "x" / "attachments" / "chan")
+        assert [p for p, _ in securecoms_transport.inbound_attachments(self._frame([good, other]))] == [good["path"]]
+
+    def test_count_is_capped(self):
+        many = [self._att(f"p{i}.jpg") for i in range(20)]
+        assert len(securecoms_transport.inbound_attachments(self._frame(many))) == securecoms_transport.MAX_INBOUND_ATTACHMENTS == 8
+        assert securecoms_transport.MAX_INBOUND_ATTACHMENT_BYTES == 5 * 1024 * 1024
+
+    def test_no_list_or_no_channel_is_empty(self):
+        good = self._att("a.jpg")
+        assert securecoms_transport.inbound_attachments({"channel_id": "chan", "attachments": good}) == []
+        assert securecoms_transport.inbound_attachments({"attachments": [good]}) == []
+        assert securecoms_transport.inbound_attachments({"channel_id": "chan"}) == []

package/connectors/openclaw/openclaw-entry.contract.test.ts

@@ -0,0 +1,96 @@
+// packages/connect-agent-bridge/connectors/openclaw/openclaw-entry.contract.test.ts
+//
+// Bridge -> connector contract (review r1 LOW): a file the daemon's REAL
+// materializeAttachment writes (real crypto, real fs writers) must pass BOTH
+// connector validators unchanged — the OpenClaw scanInboundAttachments and the
+// Hermes securecoms_transport.scan_inbound_attachments — including when the
+// daemon's attachmentsDir carries a trailing "/". A non-image the daemon saves
+// must be dropped by both.
+
+import { describe, expect, it } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { computeFileDigest, decryptFile, encryptFile, base64ToBytes } from "@agentvault/crypto";
+import {
+  materializeAttachment,
+  mkdirPrivateNoFollow,
+  writeFileExclusiveNoFollow,
+  type ArtifactShareBody,
+} from "../../src/attachments.js";
+import { inboundAttachmentsOf } from "./openclaw-entry.js";
+
+const CH = "3f2b6c1a-8d4e-4f7a-9b2c-1d3e5f7a9b0c";
+const PNG = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13, 1, 2, 3]);
+const HERMES_DIR = join(__dirname, "..", "hermes");
+
+async function materialize(plain: Uint8Array, name: string, attachmentsDir: string, messageId: string) {
+  const { encryptedData, fileKey, fileNonce, digest } = await encryptFile(plain);
+  const b64 = (u: Uint8Array) => Buffer.from(u).toString("base64");
+  const body: ArtifactShareBody = {
+    v: 1, type: "artifact_share", name, mime: "image/png", size: plain.length,
+    blobId: "0f3c2a1e-5b6d-4c7e-8f90-a1b2c3d4e5f6", fileKey: b64(fileKey), fileNonce: b64(fileNonce), digest,
+  };
+  return materializeAttachment(body, { attachmentsDir, channelId: CH, messageId }, {
+    ready: async () => {},
+    downloadBlob: async () => encryptedData,
+    decryptFile, computeFileDigest, base64ToBytes,
+    mkdirp: mkdirPrivateNoFollow,
+    writeFile: writeFileExclusiveNoFollow,
+  });
+}
+
+// Visible skip (review r2): the Hermes half needs python3 on the runner.
+const HAS_PYTHON3 = spawnSync("python3", ["--version"]).status === 0;
+
+function hermesScan(frame: unknown): { kept: Array<[string, string]>; dropped: number } {
+  const script = [
+    "import json, sys",
+    "import securecoms_transport as t",
+    "kept, dropped = t.scan_inbound_attachments(json.loads(sys.stdin.read()))",
+    "print(json.dumps({'kept': kept, 'dropped': dropped}))",
+  ].join("\n");
+  const r = spawnSync("python3", ["-c", script], {
+    input: JSON.stringify(frame),
+    cwd: HERMES_DIR,
+    env: { ...process.env, PYTHONPATH: HERMES_DIR },
+    encoding: "utf8",
+  });
+  expect(r.status, r.stderr).toBe(0);
+  return JSON.parse(r.stdout);
+}
+
+describe("bridge materializeAttachment -> connector validators", () => {
+  for (const trailing of ["", "/"]) {
+    it(`a PNG the bridge writes passes both connectors (attachmentsDir trailing "${trailing}")`, async () => {
+      const dir = join(mkdtempSync(join(tmpdir(), "sc-contract-")), "attachments") + trailing;
+      const meta = await materialize(PNG, "IMG_3375.png", dir, "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f");
+      expect(meta.mime).toBe("image/png");
+      const frame = { channel_id: CH, attachments: [meta] };
+
+      expect(inboundAttachmentsOf(frame)).toEqual([{ path: meta.path, mime: "image/png", filename: "IMG_3375.png" }]);
+
+    });
+
+    it.skipIf(!HAS_PYTHON3)(`... and the Hermes validator (attachmentsDir trailing "${trailing}")`, async () => {
+      const dir = join(mkdtempSync(join(tmpdir(), "sc-contract-")), "attachments") + trailing;
+      const meta = await materialize(PNG, "IMG_3375.png", dir, "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f");
+      expect(hermesScan({ channel_id: CH, attachments: [meta] })).toEqual({ kept: [[meta.path, "image/png"]], dropped: 0 });
+    });
+  }
+
+  it("a non-image the bridge saves is dropped by both connectors", async () => {
+    const dir = join(mkdtempSync(join(tmpdir(), "sc-contract-")), "attachments");
+    const meta = await materialize(new TextEncoder().encode("%PDF-1.7\n...."), "r.pdf", dir, "8d2e3f4a-5b6c-4d7e-9f0a-1b2c3d4e5f6a");
+    expect(meta.mime).toBe("application/octet-stream");
+    const frame = { channel_id: CH, attachments: [meta] };
+    expect(inboundAttachmentsOf(frame)).toEqual([]);
+  });
+
+  it.skipIf(!HAS_PYTHON3)("... and the Hermes validator drops it too", async () => {
+    const dir = join(mkdtempSync(join(tmpdir(), "sc-contract-")), "attachments");
+    const meta = await materialize(new TextEncoder().encode("%PDF-1.7\n...."), "r.pdf", dir, "8d2e3f4a-5b6c-4d7e-9f0a-1b2c3d4e5f6a");
+    expect(hermesScan({ channel_id: CH, attachments: [meta] })).toEqual({ kept: [], dropped: 1 });
+  });
+});

package/connectors/openclaw/openclaw-entry.inbound.test.ts

@@ -18,7 +18,8 @@
 // fake fetch for /healthz, /v1/reply-receipt, /v1/send and /v1/status.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, mkdirSync, mkdtempSync, openSync, symlinkSync, writeFileSync, writeSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { buildConnectionFile, writeConnectionFile } from "../../src/service/connection-file.js";
@@ -589,4 +590,230 @@ describe("openclaw-entry — inbound sender, session, authority, dedup (P0 Task
     await waitFor(() => acksOf(instances[0]).includes("self"));
     expect(rt.dispatches).toHaveLength(0);
   });
+
+  // ------------------------------------------------- image attachments ----
+  // The daemon decrypts an artifact_share to <attachmentsDir>/<channel_id>/
+  // and puts {filename, mime, size, path, sha256} on the frame. OpenClaw reads
+  // inbound media from the ctx fields its plugin-sdk buildAgentMediaPayload
+  // emits (MediaPath/MediaType/MediaUrl + MediaPaths/MediaUrls/MediaTypes), and
+  // only from allowed local roots; MediaWorkspaceDir adds the file's own dir.
+  // The connector checks the REAL file: images only, by magic number, <= 5 MiB.
+
+  const PNG = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+  const JPEG = Uint8Array.from([0xff, 0xd8, 0xff, 0xe0, 0, 16, 0x4a, 0x46, 0x49, 0x46, 0, 1]);
+  const GIF = new TextEncoder().encode("GIF89a\x01\x00\x01\x00\x00\x00");
+  const WEBP = new TextEncoder().encode("RIFF\x10\x00\x00\x00WEBPVP8 ");
+  let attDir: string;
+  beforeEach(() => {
+    attDir = join(mkdtempSync(join(tmpdir(), "sc-att-")), "attachments", "chan-img");
+    mkdirSync(attDir, { recursive: true });
+  });
+  const put = (name: string, bytes: Uint8Array, dir = attDir) => {
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, `m-${name}`);
+    writeFileSync(p, bytes);
+    return p;
+  };
+  const att = (name: string, bytes: Uint8Array, mime: string, dir?: string) => ({
+    filename: name, mime, size: bytes.length, path: put(name, bytes, dir), sha256: "abc",
+  });
+
+  it("an image frame sets OpenClaw's inbound media fields and keeps the caption", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    const a = att("IMG_3375.jpeg", JPEG, "image/jpeg");
+    deliver(instances[0], {
+      channel_id: "chan-img", message_id: "img-1", sender_id: OWNER_ID, text: "what is this?",
+      authorization: auth("owner_dm"), attachments: [a],
+    });
+    await waitFor(() => acksOf(instances[0]).includes("img-1"));
+    const [c] = rt.contexts;
+    expect(c.MediaPath).toBe(a.path);
+    expect(c.MediaUrl).toBe(a.path);
+    expect(c.MediaType).toBe("image/jpeg");
+    expect(c.MediaPaths).toEqual([a.path]);
+    expect(c.MediaUrls).toEqual([a.path]);
+    expect(c.MediaTypes).toEqual(["image/jpeg"]);
+    expect(c.MediaWorkspaceDir).toBe(attDir);
+    expect(c.RawBody).toBe("what is this?");
+    expect(rt.dispatches).toHaveLength(1);
+    expect(logs.some((l) => l.includes("attachments dropped"))).toBe(false);
+  });
+
+  it("an image with no caption still runs the turn, with a media placeholder body", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    const a = att("a.png", PNG, "image/png");
+    deliver(instances[0], {
+      channel_id: "chan-img", message_id: "img-2", sender_id: OWNER_ID, text: "",
+      authorization: auth("owner_dm"), attachments: [a],
+    });
+    await waitFor(() => acksOf(instances[0]).includes("img-2"));
+    expect(rt.dispatches).toHaveLength(1);
+    const [c] = rt.contexts;
+    expect(c.MediaPaths).toEqual([a.path]);
+    expect(c.RawBody).toBe("<media:image>");
+    expect(rt.envelopes[0].body).toBe("<media:image>");
+  });
+
+  it("an ungranted sender's image runs without tools or command authority", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    const a = att("r.png", PNG, "image/png");
+    deliver(instances[0], {
+      channel_id: "chan-img", message_id: "img-u", sender_id: MEMBER_ID, text: "",
+      authorization: auth("team_room"), attachments: [a],
+    });
+    await waitFor(() => acksOf(instances[0]).includes("img-u"));
+    const mod = await import("./openclaw-entry.js");
+    const [c] = rt.contexts;
+    expect(c.CommandAuthorized).toBe(false);
+    expect(c.GroupSystemPrompt).toContain(mod.NO_TOOLS_TURN_NOTE);
+    expect(c.MediaPaths).toEqual([a.path]);
+  });
+
+  it("accepts each allowed image type by its signature, reporting the sniffed lowercase mime", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const frame = (attachments: unknown) => ({ channel_id: "chan-img", attachments });
+    for (const [name, bytes, mime] of [["a.png", PNG, "image/png"], ["b.jpg", JPEG, "image/jpeg"], ["c.gif", GIF, "image/gif"], ["d.webp", WEBP, "image/webp"]] as const) {
+      const a = att(name, bytes, mime.toUpperCase());
+      expect(mod.inboundAttachmentsOf(frame([a]))).toEqual([{ path: a.path, mime, filename: name }]);
+    }
+  });
+
+  it("drops non-images, a mime mismatch, an unknown signature and an over-cap file", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const frame = (attachments: unknown) => ({ channel_id: "chan-img", attachments });
+    const big = new Uint8Array(mod.MAX_INBOUND_ATTACHMENT_BYTES + 1);
+    big.set(PNG);
+    const bad = [
+      att("v.mp3", Uint8Array.from([0x49, 0x44, 0x33, 4, 0, 0, 0, 0, 0, 0, 0, 0]), "audio/mpeg"),
+      att("v.mp4", Uint8Array.from([0, 0, 0, 0x18, 0x66, 0x74, 0x79, 0x70, 0x6d, 0x70, 0x34, 0x32]), "video/mp4"),
+      att("d.pdf", new TextEncoder().encode("%PDF-1.7\n%...."), "application/pdf"),
+      att("x.svg", new TextEncoder().encode("<svg xmlns='http://www.w3.org/2000/svg'><script/></svg>"), "image/svg+xml"),
+      att("png-as.jpg", PNG, "image/jpeg"),
+      att("t.png", new TextEncoder().encode("just some text"), "image/png"),
+      att("big.png", big, "image/png"),
+    ];
+    for (const b of bad) expect(mod.inboundAttachmentsOf(frame([b]))).toEqual([]);
+    expect(mod.scanInboundAttachments(frame(bad))).toEqual({ kept: [], dropped: bad.length });
+  });
+
+  it("drops a bad path, a control or bidi character, and caps the count", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const good = att("ok.jpg", JPEG, "image/jpeg");
+    const frame = (attachments: unknown) => ({ channel_id: "chan-img", attachments });
+    expect(mod.inboundAttachmentsOf(frame([good]))).toEqual([{ path: good.path, mime: "image/jpeg", filename: "ok.jpg" }]);
+    const outside = put("id.jpg", JPEG, join(attDir, "..", "..", "secrets", "chan-img"));
+    const other = put("o.jpg", JPEG, join(attDir, "..", "other-chan"));
+    const bad = [
+      { ...good, path: "relative/attachments/chan-img/m-ok.jpg" },
+      { ...good, path: `${attDir}/../chan-img/m-ok.jpg` },
+      { ...good, path: `${attDir}/./m-ok.jpg` },
+      { ...good, path: outside }, // not under attachments/
+      { ...good, path: other }, // another channel's dir
+      { ...good, path: `${attDir}/x\u0000.jpg` },
+      { ...good, path: put("rtl‮gpj.jpg", JPEG) },
+      { ...good, path: put("nl\n.jpg", JPEG) },
+      { ...good, filename: "inv‮fdp.jpg" },
+      { ...good, filename: 5 },
+      { ...good, path: 42 },
+      { ...good, mime: 7 },
+      null,
+      "string",
+    ];
+    for (const b of bad) expect(mod.inboundAttachmentsOf(frame([b]))).toEqual([]);
+    expect(mod.inboundAttachmentsOf(frame([...bad, good]))).toHaveLength(1);
+    // Every attachment must share one dir (the frame's channel dir).
+    const elsewhere = att("y.jpg", JPEG, "image/jpeg", join(mkdtempSync(join(tmpdir(), "sc-att2-")), "attachments", "chan-img"));
+    expect(mod.inboundAttachmentsOf(frame([good, elsewhere])).map((a: any) => a.path)).toEqual([good.path]);
+    // Cap.
+    const many = Array.from({ length: 20 }, (_, i) => att(`p${i}.jpg`, JPEG, "image/jpeg"));
+    expect(mod.inboundAttachmentsOf(frame(many))).toHaveLength(mod.MAX_INBOUND_ATTACHMENTS);
+    expect(mod.MAX_INBOUND_ATTACHMENTS).toBe(8);
+    expect(mod.MAX_INBOUND_ATTACHMENT_BYTES).toBe(5 * 1024 * 1024);
+    // Not an array / no channel.
+    expect(mod.inboundAttachmentsOf({ channel_id: "chan-img", attachments: good })).toEqual([]);
+    expect(mod.inboundAttachmentsOf({ attachments: [good] })).toEqual([]);
+  });
+
+  /** inboundAttachmentsOf in a fresh node process (own cwd, hard timeout). */
+  function scanInChild(frame: unknown, cwd?: string) {
+    const entry = join(__dirname, "openclaw-entry.js");
+    const code = `import(${JSON.stringify(entry)}).then((m) => { process.stdout.write(JSON.stringify(m.inboundAttachmentsOf(${JSON.stringify(frame)}))); process.exit(0); });`;
+    const r = spawnSync(process.execPath, ["--input-type=module", "-e", code], { encoding: "utf8", timeout: 15_000, cwd });
+    expect(r.signal, "child timed out (blocked open?)").toBeNull();
+    expect(r.status, r.stderr).toBe(0);
+    return JSON.parse(r.stdout);
+  }
+
+  it("guards that only normalize / isAbsolute / isFile catch (review r2 mutation survivors)", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const frame = (attachments: unknown) => ({ channel_id: "chan-img", attachments });
+    const root = join(attDir, "..", "..");
+    // A real image reachable through an UNnormalized path whose literal parent
+    // is .../attachments/chan-img: only the normalize() equality rejects it.
+    put("f.png", PNG, join(root, "y", "attachments", "chan-img"));
+    const dotted = `${root}/attachments/chan-img/../../y/attachments/chan-img/m-f.png`;
+    expect(mod.inboundAttachmentsOf(frame([{ path: dotted, mime: "image/png" }]))).toEqual([]);
+    // A relative path that resolves to a real image from the cwd: only
+    // isAbsolute rejects it (run in a child: workers cannot chdir).
+    put("rel.png", PNG);
+    expect(scanInChild(frame([{ path: "attachments/chan-img/m-rel.png", mime: "image/png" }]), root)).toEqual([]);
+    // A FIFO that holds PNG bytes (a writer keeps it open): only the
+    // regular-file check rejects it.
+    const fifo = join(attDir, "m-fifo.png");
+    expect(spawnSync("mkfifo", [fifo]).status).toBe(0);
+    const holder = openSync(fifo, fsConstants.O_RDWR | fsConstants.O_NONBLOCK);
+    try {
+      writeSync(holder, PNG);
+      expect(mod.inboundAttachmentsOf(frame([{ path: fifo, mime: "image/png" }]))).toEqual([]);
+    } finally {
+      closeSync(holder);
+    }
+  });
+
+  it("a FIFO with no writer is dropped without hanging (O_NONBLOCK)", () => {
+    const fifo = join(attDir, "m-hang.png");
+    expect(spawnSync("mkfifo", [fifo]).status).toBe(0);
+    // In a child with a timeout: without O_NONBLOCK, open() blocks forever.
+    expect(scanInChild({ channel_id: "chan-img", attachments: [{ path: fifo, mime: "image/png" }] })).toEqual([]);
+  });
+
+  it("a symlinked attachment is not followed", async () => {
+    const mod = await import("./openclaw-entry.js");
+    const target = put("real.png", PNG, join(attDir, "..", "..", "elsewhere"));
+    const link = join(attDir, "m-link.png");
+    symlinkSync(target, link);
+    expect(mod.inboundAttachmentsOf({ channel_id: "chan-img", attachments: [{ path: link, mime: "image/png" }] })).toEqual([]);
+  });
+
+  it("a frame whose only attachment is invalid sets no media fields and logs a content-free drop count", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    deliver(instances[0], {
+      channel_id: "chan-img", message_id: "img-3", sender_id: OWNER_ID, text: "look",
+      authorization: auth("owner_dm"), attachments: [{ ...att("x.jpg", JPEG, "image/jpeg"), path: "/etc/passwd" }],
+    });
+    await waitFor(() => acksOf(instances[0]).includes("img-3"));
+    const [c] = rt.contexts;
+    for (const k of ["MediaPath", "MediaPaths", "MediaType", "MediaTypes", "MediaUrl", "MediaUrls", "MediaWorkspaceDir"]) {
+      expect(k in c).toBe(false);
+    }
+    expect(c.RawBody).toBe("look");
+    const line = logs.find((l) => l.includes("attachments dropped"));
+    expect(line).toBe("[securecoms] inbound attachments dropped=1 kept=0");
+  });
+
+  it("a text-only frame is unchanged: no media fields, same body", async () => {
+    const rt = makeRuntime();
+    const { instances } = await start(rt.runtime);
+    deliver(instances[0], { channel_id: "chan-t", message_id: "t-1", sender_id: OWNER_ID, text: "hello", authorization: auth("owner_dm") });
+    await waitFor(() => acksOf(instances[0]).includes("t-1"));
+    const [c] = rt.contexts;
+    expect(Object.keys(c).filter((k) => k.startsWith("Media"))).toEqual([]);
+    expect(c.RawBody).toBe("hello");
+    expect(c.CommandBody).toBe("hello");
+    expect(rt.envelopes[0].body).toBe("hello");
+  });
 });

package/connectors/openclaw/openclaw-entry.js

@@ -51,9 +51,9 @@
  * from a file.
  */
 
-import { readFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, fstatSync, openSync, readFileSync, readSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize } from "node:path";
 import { evaluateGate, resolveBoundIdentity, backoffDelayMs } from "./gate.js";
 
 // Runtime injected by register() — used by the inbound handler.
@@ -104,6 +104,119 @@ export function voiceGuidanceOf(frame) {
   const g = frame.guidance.trim().slice(0, VOICE_GUIDANCE_MAX_CHARS);
   return g || undefined;
 }
+// Inbound attachments. For an artifact_share the daemon decrypts the file to
+// <attachmentsDir>/<channel_id>/<message_id>-<name> and puts
+// {filename, mime, size, path, sha256} on the frame. The frame's fields are
+// claims; only a file that passes ALL of these reaches OpenClaw:
+//   - path: a string, absolute and already normalized (normalize() collapses
+//     any "." or ".." segment, so an unnormalized path, including any ".."
+//     traversal, fails the equality), no C0/C1 control or bidi character,
+//     parent dir == the frame's channel id inside a dir named "attachments",
+//     every kept file in one dir;
+//   - filename (when present): no control or bidi character;
+//   - the file itself (opened O_NOFOLLOW|O_NONBLOCK): a regular file of at most
+//     MAX_INBOUND_ATTACHMENT_BYTES whose first bytes are a PNG, JPEG, GIF or
+//     WEBP signature, and the claimed mime equals that sniffed type.
+// Images only: no SVG (script), audio, video or documents. Anything else is
+// dropped; at most MAX_INBOUND_ATTACHMENTS are kept.
+export const MAX_INBOUND_ATTACHMENTS = 8;
+export const MAX_INBOUND_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+const FORBIDDEN_CHARS = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+
+/** The image type from a file's leading bytes, or undefined. */
+export function sniffImageMime(b) {
+  if (!b || b.length < 3) return undefined;
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 &&
+      b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a) return "image/png";
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg";
+  if (b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 &&
+      (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61) return "image/gif";
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) return "image/webp";
+  return undefined;
+}
+
+/** The sniffed image mime of a regular file within the size cap, else undefined. */
+function _sniffFile(path) {
+  let fd;
+  try {
+    // O_NONBLOCK: a FIFO planted at the path must not hang the gateway in
+    // open(); fstat below then drops it as not a regular file.
+    fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > MAX_INBOUND_ATTACHMENT_BYTES) return undefined;
+    const head = Buffer.alloc(12);
+    const n = readSync(fd, head, 0, 12, 0);
+    return sniffImageMime(head.subarray(0, n));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* ignore */ }
+  }
+}
+
+/** Validate a frame's attachments: { kept: [{path, mime, filename?}], dropped }. */
+export function scanInboundAttachments(frame) {
+  const raw = frame?.attachments;
+  const channelId = frame?.channel_id;
+  if (!Array.isArray(raw)) return { kept: [], dropped: 0 };
+  if (typeof channelId !== "string" || channelId === "") return { kept: [], dropped: raw.length };
+  const kept = [];
+  let dir;
+  for (const a of raw) {
+    if (kept.length >= MAX_INBOUND_ATTACHMENTS) break;
+    if (a === null || typeof a !== "object") continue;
+    const { path, mime, filename } = a;
+    if (typeof path !== "string" || typeof mime !== "string") continue;
+    if (filename !== undefined && (typeof filename !== "string" || FORBIDDEN_CHARS.test(filename))) continue;
+    if (FORBIDDEN_CHARS.test(path) || !isAbsolute(path) || normalize(path) !== path) continue;
+    const parent = dirname(path);
+    if (basename(parent) !== channelId || basename(dirname(parent)) !== "attachments") continue;
+    if (dir !== undefined && parent !== dir) continue;
+    const sniffed = _sniffFile(path);
+    if (sniffed === undefined || sniffed !== mime.toLowerCase()) continue;
+    dir ??= parent;
+    kept.push({ path, mime: sniffed, ...(typeof filename === "string" ? { filename } : {}) });
+  }
+  return { kept, dropped: raw.length - kept.length };
+}
+
+/** The attachments of a frame that pass every check (see above). */
+export function inboundAttachmentsOf(frame) {
+  return scanInboundAttachments(frame).kept;
+}
+
+// OpenClaw's own placeholder body for a media-only message (as its bundled
+// channels use), so a turn with no caption still has a body.
+function mediaPlaceholder(mime) {
+  const kind = mime.split("/", 1)[0];
+  if (kind === "image" || kind === "video" || kind === "audio") return `<media:${kind}>`;
+  return "<media:document>";
+}
+
+/**
+ * The inbound media ctx fields, in the shape of OpenClaw's plugin-sdk
+ * buildAgentMediaPayload (src/plugin-sdk/agent-media-payload.ts). OpenClaw
+ * reads a local media file only inside its allowed roots (its own media/,
+ * workspace, tmp dirs) plus ctx.MediaWorkspaceDir, the same field its webchat
+ * sets for offloaded files. Setting it to the attachments' own per-channel dir
+ * lets OpenClaw read exactly these files without a config change or a copy.
+ */
+export function inboundMediaFields(attachments) {
+  if (!Array.isArray(attachments) || attachments.length === 0) return {};
+  const paths = attachments.map((a) => a.path);
+  const types = attachments.map((a) => a.mime);
+  return {
+    MediaPath: paths[0],
+    MediaType: types[0],
+    MediaUrl: paths[0],
+    MediaPaths: paths,
+    MediaUrls: paths,
+    MediaTypes: types,
+    MediaWorkspaceDir: dirname(paths[0]),
+  };
+}
+
 const SEEN_MAX = 5000;
 
 /** Thrown by the inbound handler when register() has not injected a runtime. */
@@ -671,6 +784,11 @@ export class LoopbackChannel {
         this._ack(messageId);
         return;
       }
+      const { kept: attachments, dropped } = scanInboundAttachments(frame);
+      if (dropped > 0) {
+        // Content-free: counts only, never a path, name or mime.
+        this._logSafe("[securecoms] inbound attachments dropped={d} kept={k}", { d: dropped, k: attachments.length });
+      }
       await this.onMessage?.(typeof frame.text === "string" ? frame.text : "", {
         conversationId: frame.channel_id,
         messageId,
@@ -679,6 +797,7 @@ export class LoopbackChannel {
         authorization: frame.authorization,
         timestamp: frame.ts,
         voiceGuidance: voiceGuidanceOf(frame),
+        attachments,
       });
       this._failures.delete(messageId);
       this._failStreak = 0;
@@ -839,9 +958,14 @@ export class LoopbackChannel {
 // SecureComs channel the message arrived on (closure over metadata).
 // ---------------------------------------------------------------------------
 
-async function _handleInbound({ text, metadata, channel, account, cfg }) {
+async function _handleInbound({ text: rawText, metadata, channel, account, cfg }) {
   const core = _runtime;
   if (!core) throw new RuntimeNotReadyError();
+  const attachments = Array.isArray(metadata.attachments) ? metadata.attachments : [];
+  // An image with no caption still runs the turn: give it OpenClaw's media
+  // placeholder body rather than an empty one.
+  const caption = typeof rawText === "string" ? rawText : "";
+  const text = caption.trim() === "" && attachments.length > 0 ? mediaPlaceholder(attachments[0].mime) : caption;
 
   const conv = metadata.conversationId;
   if (typeof conv !== "string" || conv === "") {
@@ -941,6 +1065,7 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
     // this turn's extra system prompt (get-reply's extraSystemPromptParts)
     // for any chat type.
     ...(extraPrompt ? { GroupSystemPrompt: extraPrompt } : {}),
+    ...inboundMediaFields(attachments),
   });
 
   await core.channel.session.recordInboundSession({