@securecoms/agent-bridge 0.37.0 → 0.39.0

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,213 @@ export function voiceGuidanceOf(frame) {
   const g = frame.guidance.trim().slice(0, VOICE_GUIDANCE_MAX_CHARS);
   return g || undefined;
 }
+// Display names (R3). sender_name and a relayed voice turn's speaker name are
+// member-chosen strings that reach the LLM prompt (SenderName and the
+// envelope's "from"), so they must not be able to start a new line or fake
+// prompt structure. A label only: identity (SenderId/From), the session key
+// and every authorization decision stay on sender_id and the daemon's
+// authorization block. The Hermes connector's twin is
+// securecoms_transport.display_name/sender_label; both are pinned to the same
+// cases by ../display-name-fixtures.json. Residual drift: \p{...} classes come
+// from the JS engine's Unicode tables and the twin's from Python unicodedata,
+// so a character assigned in a newer Unicode version can be "unassigned,
+// dropped" in one runtime and kept in the other.
+export const DISPLAY_NAME_MAX = 64;
+/** Characters of the sender id shown in a label's trusted suffix. */
+export const LABEL_ID_CHARS = 8;
+// These C0/C1 controls become a space (as Python isspace and JS \s do), every
+// other \p{C} is dropped, every \p{Z} becomes a space.
+const NAME_SPACE = /[\p{Z}\t\n\v\f\r\u001c-\u001f\u0085]/u;
+// \p{C}, plus letters that render as nothing (Hangul fillers, blank braille)
+// so a blank-looking name falls back to the id.
+const NAME_DROP = /[\p{C}\u115f\u1160\u3164\uffa0\u2800]/u;
+// Stripped from the NAME part of a label, after NFKC folds compatibility
+// lookalikes (fullwidth, small, superscript forms) to their ASCII originals:
+// every opening/closing/initial/final punctuation character (Ps/Pe/Pi/Pf, so
+// any bracket or quote Unicode classifies as one) plus "<>|" and the backtick.
+// That keeps a name from faking the trusted " (owner)" / " (<id>)" suffix, a
+// tag or a table cell with any bracket Unicode classifies as such. A glyph
+// that merely looks like a bracket but is classified otherwise is not caught.
+const LABEL_STRUCTURE = /[\p{Ps}\p{Pe}\p{Pi}\p{Pf}<>|`]/gu;
+
+/**
+ * Whitespace (newlines, tabs, Unicode line/paragraph separators) becomes one
+ * space; other control, format (bidi, zero-width), surrogate, private-use and
+ * unassigned characters and invisible fillers are dropped; runs of spaces
+ * collapse; the result is trimmed and capped at DISPLAY_NAME_MAX code points.
+ * "" for a non-string or nothing left.
+ */
+export function displayName(raw) {
+  if (typeof raw !== "string") return "";
+  let out = "";
+  for (const ch of raw) {
+    if (NAME_SPACE.test(ch)) out += " ";
+    else if (!NAME_DROP.test(ch)) out += ch;
+  }
+  return Array.from(out.split(" ").filter(Boolean).join(" ")).slice(0, DISPLAY_NAME_MAX).join("").trimEnd();
+}
+
+function labelName(raw) {
+  return typeof raw === "string" ? displayName(raw.normalize("NFKC").replace(LABEL_STRUCTURE, "")) : "";
+}
+
+/** The daemon's v1 block for an active sender, else undefined. */
+function validAuthorization(authorization) {
+  if (authorization === null || typeof authorization !== "object") return undefined;
+  if (authorization.version !== 1 || authorization.sender_membership !== "active") return undefined;
+  return authorization;
+}
+
+/**
+ * name + a suffix built only from trusted data: " (owner)" when the daemon's
+ * block says so, else " (<first LABEL_ID_CHARS of the id>)". No usable name:
+ * the id itself (plus " (owner)" for the owner).
+ */
+function label(rawName, rawId, isOwner) {
+  const name = labelName(rawName);
+  const id = labelName(rawId);
+  if (name) return `${name} (${isOwner ? "owner" : Array.from(id).slice(0, LABEL_ID_CHARS).join("") || "unknown"})`;
+  if (id && isOwner) return `${id} (owner)`;
+  return id;
+}
+
+/** The frame sender's label (the relay itself on a relayed voice turn). Owner only on an owner_dm block. */
+export function ownLabel({ senderName, senderId, authorization } = {}) {
+  return label(senderName, senderId, validAuthorization(authorization)?.audience === "owner_dm");
+}
+
+/**
+ * A relayed voice turn's speaker label, or "" when there is no speaker with a
+ * usable identityId. Owner only on the daemon's relay_speaker "owner" mark,
+ * never on what the speaker claims.
+ */
+export function speakerLabel(speaker, authorization) {
+  if (speaker === null || typeof speaker !== "object" || Array.isArray(speaker) || !labelName(speaker.identityId)) return "";
+  return label(speaker.displayName, speaker.identityId, validAuthorization(authorization)?.relay_speaker === "owner");
+}
+
+/**
+ * Who the model is told spoke this turn: the relayed speaker when there is
+ * one, else the sender. Display data only, never an authorization or session
+ * input.
+ */
+export function senderLabel({ speaker, senderName, senderId, authorization } = {}) {
+  return speakerLabel(speaker, authorization) || ownLabel({ senderName, senderId, authorization });
+}
+
+// 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,14 +878,23 @@ 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,
         senderId: frame.sender_id,
         senderName: frame.sender_name,
+        senderIsAgent: frame.sender_is_agent,
+        // A relayed voice turn's real speaker: display data only (R3).
+        speaker: frame.speaker,
         authorization: frame.authorization,
         timestamp: frame.ts,
         voiceGuidance: voiceGuidanceOf(frame),
+        attachments,
       });
       this._failures.delete(messageId);
       this._failStreak = 0;
@@ -839,9 +1055,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 === "") {
@@ -852,7 +1073,19 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
   // are separate facts, and only the daemon's authorization block speaks to
   // the second.
   const senderId = typeof metadata.senderId === "string" && metadata.senderId !== "" ? metadata.senderId : "unknown";
-  const senderName = typeof metadata.senderName === "string" && metadata.senderName !== "" ? metadata.senderName : senderId;
+  // The label the model sees: sanitized, and on a relayed voice turn the
+  // speaker's name (R3). Never used for identity, the session or authority.
+  const senderName = senderLabel({
+    speaker: metadata.speaker,
+    senderName: metadata.senderName,
+    senderId: metadata.senderId,
+    authorization: metadata.authorization,
+  }) || senderId;
+  // A relayed speaker is a human (the relay stamps speaker only on a human
+  // turn), so the labelled sender is not a bot even though the relay is.
+  const senderIsBot = speakerLabel(metadata.speaker, metadata.authorization)
+    ? false
+    : typeof metadata.senderIsAgent === "boolean" ? metadata.senderIsAgent : undefined;
   const chatType = chatTypeFor(metadata.authorization);
   const commandAuthorized = isOwnerAuthorization(metadata.authorization);
   if (metadata.authorization === null || typeof metadata.authorization !== "object") {
@@ -927,6 +1160,7 @@ async function _handleInbound({ text, metadata, channel, account, cfg }) {
     ConversationLabel: "SecureComs",
     SenderName: senderName,
     SenderId: senderId,
+    ...(senderIsBot === undefined ? {} : { SenderIsBot: senderIsBot }),
     Provider: "securecoms",
     Surface: "securecoms",
     MessageSid: metadata.messageId,
@@ -941,6 +1175,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({

package/dist/attachments.d.ts

@@ -95,9 +95,41 @@ export interface ReceiveDeps {
     mkdirp(dir: string): Promise<void>;
     writeFile(p: string, data: Uint8Array): Promise<void>;
 }
-/** Reduce any name to a safe basename inside the target dir. Strips path
+/** Reduce any name to a safe basename inside the target dir. Strips control
+ *  and bidi characters (review r1 M1: "invoice\u202Efdp.exe"), path
  *  separators and `..`; falls back when nothing usable remains. */
 export declare function sanitizeFilename(name: string, fallback: string): string;
+/**
+ * The image type from a file's leading bytes (PNG, JPEG, GIF, WEBP), or
+ * undefined. Review r1 H1: the reported mime of a received file is derived
+ * from its decrypted bytes, never the sender's claim. Twin of the connectors'
+ * sniffImageMime / sniff_image_mime.
+ */
+export declare function sniffImageMime(b: Uint8Array): string | undefined;
+/** A channel or message id that is not a canonical lowercase UUID would become
+ *  a path segment of the attachments dir. Content-free: the id is never echoed. */
+export declare class InvalidAttachmentTargetError extends Error {
+    constructor();
+}
+/** mkdir -p with 0700, then refuse the leaf if it is not a real directory
+ *  (a symlink planted at <attachmentsDir>/<channel> is never written through). */
+export declare function mkdirPrivateNoFollow(dir: string): Promise<void>;
+/** Byte cap on a saved attachment's name: with the "<uuid>-" prefix and the
+ *  ".<uuid>.part" temp suffix the entry stays far below NAME_MAX (255). */
+export declare const MAX_FILENAME_BYTES = 150;
+/** Truncate `name` to at most `maxBytes` UTF-8 bytes, cutting only between
+ *  code points and keeping a short extension. */
+export declare function truncateFilename(name: string, maxBytes?: number): string;
+/**
+ * Review r1 M4: write `data` to `path` without following a symlink and
+ * without writing into an existing file. The bytes go to a fresh temp name
+ * opened O_CREAT|O_EXCL|O_NOFOLLOW (0600), then rename() moves it into place.
+ * rename replaces a directory ENTRY, never writes through a link at `path`,
+ * and keeps a redelivered message (same id, same path) idempotent: a plain
+ * exclusive create of `path` itself would fail the redelivery, and the
+ * fail-soft share path would ack it and lose the file.
+ */
+export declare function writeFileExclusiveNoFollow(path: string, data: Uint8Array): Promise<void>;
 export declare function mimeForName(name: string): string;
 export interface SendDeps {
     /** Warm libsodium before any WASM-backed call. See src/sodium-ready.ts. */