@securecoms/agent-bridge 0.37.0 → 0.39.0

package/connectors/hermes/securecoms_authz.py

@@ -113,6 +113,56 @@ def tools_allowed(frame: Any) -> bool:
     return all(_is_grant(g) for g in grants)
 
 
+# H0.2c (re-ruled after code audit r1): Hermes keys a DM session by chat only,
+# so every non-owner DM turn (a guest's relayed voice, any other sender, a frame
+# with no valid block) runs in its own Hermes session, selected by this
+# thread id. No ":" (Hermes joins session-key parts with ":"). A ledger record
+# under this thread is never a grant.
+NON_OWNER_THREAD = "sc-non-owner"
+# Audit r2 (ruled): a DM frame whose block cannot be classified (missing,
+# malformed, wrong version, or sender_membership not "active", e.g. the owner
+# during a stale roster) runs in a THIRD session, never the owner's and never
+# the guests'. Forced ungranted like NON_OWNER_THREAD.
+UNCLASSIFIED_THREAD = "sc-unclassified"
+_FORCED_OFF_THREADS = (NON_OWNER_THREAD, UNCLASSIFIED_THREAD)
+# authorizationFor (bridge-agent.ts:9093-9094) sets these audiences only when
+# the channel is a DM, and sets relay_speaker only inside its is_dm branch.
+_DM_AUDIENCES = ("owner_dm", "other_human_dm")
+
+
+def is_owner_turn(frame: Any) -> bool:
+    """True only for a valid block with ``audience == "owner_dm"`` or the
+    daemon's ``relay_speaker: "owner"`` mark (granted or not). Anything else,
+    including no block or a malformed one, is a non-owner turn."""
+    block = _valid_block(frame)
+    if block is None:
+        return False
+    return block.get("audience") == "owner_dm" or block.get("relay_speaker") == "owner"
+
+
+def dm_thread(frame: Any) -> Optional[str]:
+    """The Hermes thread for a DM turn: None for an owner turn (owner session),
+    UNCLASSIFIED_THREAD when the block cannot be classified, else
+    NON_OWNER_THREAD."""
+    if _valid_block(frame) is None:
+        return UNCLASSIFIED_THREAD
+    return None if is_owner_turn(frame) else NON_OWNER_THREAD
+
+
+def block_says_dm(frame: Any) -> bool:
+    """True when the daemon's block marks this turn as a DM turn (a DM
+    audience or any relay_speaker mark). Read from the raw block, valid or
+    not: it only ever moves a turn OUT of a shared session, never grants."""
+    block = frame.get("authorization") if isinstance(frame, dict) else None
+    if not isinstance(block, dict):
+        return False
+    return block.get("audience") in _DM_AUDIENCES or "relay_speaker" in block
+
+
+def _thread_key(thread_id: Any) -> Any:
+    return "" if thread_id is None else thread_id
+
+
 def sender_role(frame: Any) -> str:
     """owner / member / other_org / agent / unknown, from the daemon's
     audience. Descriptive metadata for Hermes, never an authorization input:
@@ -124,12 +174,24 @@ def sender_role(frame: Any) -> str:
 
 
 class TurnAuthzLedger:
-    """The tool decision of the latest inbound frame per (chat_id, sender).
+    """The tool decision of the latest inbound frame per (chat_id, sender,
+    thread), held down by any ungranted turn for that key still in flight.
 
     Hermes runs a turn later, on its own task, so the decision is recorded at
-    dispatch and looked up when a tool is about to run (by the chat and user
-    Hermes binds to that turn's session). Unrecorded or evicted keys have no
-    tools.
+    dispatch and looked up when a tool is about to run (by the chat, user and
+    thread Hermes binds to that turn's session). Unrecorded or evicted keys
+    have no tools. A record under NON_OWNER_THREAD or UNCLASSIFIED_THREAD is
+    always "no tools".
+
+    H0 (audit r1 #3, r2 #1): the latest decision alone let a guest's turn that
+    was still running borrow a grant recorded later for the same key. An
+    ungranted event therefore holds an in-flight count (begin_ungranted /
+    end_ungranted) until no turn in its Hermes session can still be processing
+    its text; while the count is above zero the key has no tools, whatever the
+    latest decision says. A ``shared_session`` count (H0.2b: a room whose
+    Hermes session is shared by every sender) blocks every key in that chat.
+    The counts are never evicted (dropping one would fail open) and a grant
+    never lowers them.
     """
 
     def __init__(self, max_entries: int = 4096):
@@ -139,13 +201,42 @@ class TurnAuthzLedger:
         # channel), so a chat whose decision was evicted is still known to be
         # SecureComs and its tool calls are still gated.
         self._chats: set = set()
+        # In-flight ungranted events per (chat_id, user_id, thread), and per
+        # chat for shared room sessions. Never evicted by max_entries.
+        self._inflight: Dict[tuple, int] = {}
+        self._inflight_chat: Dict[Any, int] = {}
+
+    def begin_ungranted(self, chat_id: Any, user_id: Any, thread_id: Any = None, shared_session: bool = False) -> None:
+        key = (chat_id, user_id, _thread_key(thread_id))
+        if isinstance(chat_id, str) and chat_id:
+            self._chats.add(chat_id)
+        self._inflight[key] = self._inflight.get(key, 0) + 1
+        if shared_session:
+            self._inflight_chat[chat_id] = self._inflight_chat.get(chat_id, 0) + 1
+
+    def end_ungranted(self, chat_id: Any, user_id: Any, thread_id: Any = None, shared_session: bool = False) -> None:
+        key = (chat_id, user_id, _thread_key(thread_id))
+        n = self._inflight.get(key, 0)
+        if n <= 1:
+            self._inflight.pop(key, None)
+        else:
+            self._inflight[key] = n - 1
+        if shared_session:
+            c = self._inflight_chat.get(chat_id, 0)
+            if c <= 1:
+                self._inflight_chat.pop(chat_id, None)
+            else:
+                self._inflight_chat[chat_id] = c - 1
 
-    def record(self, chat_id: Any, user_id: Any, allowed: bool) -> None:
-        key = (chat_id, user_id)
+    def ungranted_in_flight(self, chat_id: Any, user_id: Any, thread_id: Any = None) -> int:
+        return self._inflight.get((chat_id, user_id, _thread_key(thread_id)), 0)
+
+    def record(self, chat_id: Any, user_id: Any, allowed: bool, thread_id: Any = None) -> None:
+        key = (chat_id, user_id, _thread_key(thread_id))
         if isinstance(chat_id, str) and chat_id:
             self._chats.add(chat_id)
         self._entries.pop(key, None)
-        self._entries[key] = allowed is True
+        self._entries[key] = allowed is True and thread_id not in _FORCED_OFF_THREADS
         while len(self._entries) > self._max:
             self._entries.popitem(last=False)
 
@@ -155,10 +246,15 @@ class TurnAuthzLedger:
             return False
         return chat_id in self._chats
 
-    def tools_allowed(self, chat_id: Any, user_id: Any) -> bool:
+    def tools_allowed(self, chat_id: Any, user_id: Any, thread_id: Any = None) -> bool:
         if not isinstance(chat_id, str) or not chat_id or not isinstance(user_id, str) or not user_id:
             return False
-        return self._entries.get((chat_id, user_id)) is True
+        if thread_id is not None and not isinstance(thread_id, str):
+            return False
+        key = (chat_id, user_id, _thread_key(thread_id))
+        if self._inflight.get(key, 0) > 0 or self._inflight_chat.get(chat_id, 0) > 0:
+            return False
+        return self._entries.get(key) is True
 
 
 def pre_tool_call_decision(
@@ -180,14 +276,19 @@ def pre_tool_call_decision(
       Hermes's task-local cron ContextVar; the environment never counts
       (None = no exemption).
     - Any other platform: no opinion.
-    A failure to read the session blocks.
+    A failure to read the session blocks. ``get_session_env(name, default)``
+    returns the turn's task-local value, or None when the variable is unset in
+    this task (no environment fallback): an unset or empty chat or user, or an
+    unset thread, blocks a SecureComs turn. The thread is "" for an owner turn.
     """
     try:
         platform = get_session_env("HERMES_SESSION_PLATFORM", "")
         chat_id = get_session_env("HERMES_SESSION_CHAT_ID", "")
         user_id = get_session_env("HERMES_SESSION_USER_ID", "")
+        thread_id = get_session_env("HERMES_SESSION_THREAD_ID", "")
+        platform = "" if platform is None else platform
         if platform == PLATFORM_ID or ledger.knows_chat(chat_id):
-            if ledger.tools_allowed(chat_id, user_id):
+            if isinstance(thread_id, str) and ledger.tools_allowed(chat_id, user_id, thread_id or None):
                 return None
         elif platform == "":
             engaged = True if session_engaged is None else session_engaged() is not False

package/connectors/hermes/securecoms_transport.py

@@ -26,7 +26,10 @@ from __future__ import annotations
 
 import json
 import os
-from typing import Awaitable, Callable, Mapping, NamedTuple, Optional, Tuple
+import re
+import stat
+import unicodedata
+from typing import Awaitable, Callable, List, Mapping, NamedTuple, Optional, Tuple
 
 from securecoms_gate import evaluate_gate, resolve_bound_identity
 
@@ -196,6 +199,208 @@ def should_drop_inbound(frame: dict, bound_identity: str) -> bool:
     return bool(sender_id) and bool(bound_identity) and sender_id == bound_identity
 
 
+# Display names (R3). sender_name, a relayed voice turn's speaker name and a
+# room name are member-chosen strings that reach the LLM prompt, so they must
+# not be able to start a new line or fake prompt structure. Python twin of
+# openclaw-entry.js's displayName/senderLabel; both are pinned to the same
+# cases by ../display-name-fixtures.json. Residual drift: character
+# categories come from each runtime's Unicode tables (Python unicodedata vs
+# the JS engine's ICU), so a character assigned in a newer Unicode version
+# can be "unassigned, dropped" in one runtime and kept in the other.
+# A label only: identity, sessions and authorization stay on sender_id and the
+# daemon's authorization block.
+DISPLAY_NAME_MAX = 64
+# These C0/C1 controls become a space (as Python isspace and JS \s do); every
+# other C* character is dropped; every Z* character becomes a space.
+_NAME_SPACE_CONTROLS = frozenset("\t\n\v\f\r\x1c\x1d\x1e\x1f\x85")
+# Letters (Lo/So) that render as nothing: Hangul fillers and the blank braille
+# pattern. Dropped so a blank-looking name falls back to the id.
+_INVISIBLE_LETTERS = frozenset("\u115f\u1160\u3164\uffa0\u2800")
+# 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
+# "[name]" turn prefix, 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 (e.g. a letter or symbol) is not caught.
+_LABEL_STRUCTURE = frozenset("<>|`")
+_LABEL_STRUCTURE_CATEGORIES = frozenset(("Ps", "Pe", "Pi", "Pf"))
+LABEL_ID_CHARS = 8
+
+
+def display_name(raw: object) -> str:
+    """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."""
+    if not isinstance(raw, str):
+        return ""
+    out = []
+    for ch in raw:
+        cat = unicodedata.category(ch)
+        if ch in _NAME_SPACE_CONTROLS or cat[0] == "Z":
+            out.append(" ")
+        elif cat[0] != "C" and ch not in _INVISIBLE_LETTERS:
+            out.append(ch)
+    return " ".join("".join(out).split())[:DISPLAY_NAME_MAX].rstrip()
+
+
+def _label_name(raw: object) -> str:
+    if not isinstance(raw, str):
+        return ""
+    folded = unicodedata.normalize("NFKC", raw)
+    return display_name("".join(
+        ch for ch in folded
+        if ch not in _LABEL_STRUCTURE and unicodedata.category(ch) not in _LABEL_STRUCTURE_CATEGORIES))
+
+
+def _valid_authorization(frame: Mapping) -> Optional[Mapping]:
+    """The daemon's v1 block for an active sender (securecoms_authz's rule)."""
+    block = frame.get("authorization")
+    if not isinstance(block, dict):
+        return None
+    version = block.get("version")
+    if version != 1 or isinstance(version, bool) or block.get("sender_membership") != "active":
+        return None
+    return block
+
+
+def _label(raw_name: object, raw_id: object, is_owner: bool) -> str:
+    """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)."""
+    name = _label_name(raw_name)
+    ident = _label_name(raw_id)
+    if name:
+        return f"{name} ({'owner' if is_owner else (ident[:LABEL_ID_CHARS] or 'unknown')})"
+    if ident and is_owner:
+        return f"{ident} (owner)"
+    return ident
+
+
+def own_label(frame: Mapping) -> str:
+    """The frame sender's label (the relay itself on a relayed voice turn).
+    Owner only on the daemon's owner_dm block."""
+    block = _valid_authorization(frame)
+    is_owner = block is not None and block.get("audience") == "owner_dm"
+    return _label(frame.get("sender_name"), frame.get("sender_id"), is_owner)
+
+
+def speaker_label(frame: Mapping) -> str:
+    """A relayed voice turn's speaker label, or "" when the frame has no
+    speaker with a usable identityId. Owner only on the daemon's
+    relay_speaker="owner" mark (never on what the speaker claims)."""
+    speaker = frame.get("speaker")
+    if not isinstance(speaker, dict) or not _label_name(speaker.get("identityId")):
+        return ""
+    block = _valid_authorization(frame)
+    is_owner = block is not None and block.get("relay_speaker") == "owner"
+    return _label(speaker.get("displayName"), speaker.get("identityId"), is_owner)
+
+
+def sender_label(frame: Mapping) -> str:
+    """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."""
+    return speaker_label(frame) or own_label(frame)
+
+
+# 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. Python twin of
+# openclaw-entry.js's scanInboundAttachments. The frame's fields are claims;
+# only a file that passes ALL of these reaches Hermes:
+#   - path: a string, absolute and already normalized (normpath collapses any
+#     "." or ".." segment and a trailing "/", so any traversal or an empty
+#     basename 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. Anything else is dropped; at most MAX_INBOUND_ATTACHMENTS kept.
+MAX_INBOUND_ATTACHMENTS = 8
+MAX_INBOUND_ATTACHMENT_BYTES = 5 * 1024 * 1024
+_FORBIDDEN_CHARS = re.compile("[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]")
+
+
+def sniff_image_mime(b: bytes) -> Optional[str]:
+    """The image type from a file's leading bytes, or None."""
+    if b.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if b.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if b.startswith(b"GIF87a") or b.startswith(b"GIF89a"):
+        return "image/gif"
+    if len(b) >= 12 and b[:4] == b"RIFF" and b[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def _sniff_file(path: str) -> Optional[str]:
+    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 = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
+    except OSError:
+        return None
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode) or st.st_size > MAX_INBOUND_ATTACHMENT_BYTES:
+            return None
+        return sniff_image_mime(os.pread(fd, 12, 0))
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+
+
+def scan_inbound_attachments(frame: dict) -> Tuple[List[Tuple[str, str]], int]:
+    """(kept (path, sniffed mime) pairs, dropped count) for a daemon frame."""
+    raw = frame.get("attachments") if isinstance(frame, dict) else None
+    channel_id = frame.get("channel_id") if isinstance(frame, dict) else None
+    if not isinstance(raw, list):
+        return [], 0
+    if not isinstance(channel_id, str) or not channel_id:
+        return [], len(raw)
+    kept: List[Tuple[str, str]] = []
+    first_dir: Optional[str] = None
+    for a in raw:
+        if len(kept) >= MAX_INBOUND_ATTACHMENTS:
+            break
+        if not isinstance(a, dict):
+            continue
+        path, mime, filename = a.get("path"), a.get("mime"), a.get("filename")
+        if not isinstance(path, str) or not isinstance(mime, str):
+            continue
+        if filename is not None and (not isinstance(filename, str) or _FORBIDDEN_CHARS.search(filename)):
+            continue
+        if _FORBIDDEN_CHARS.search(path) or not os.path.isabs(path) or os.path.normpath(path) != path:
+            continue
+        parent = os.path.dirname(path)
+        if not os.path.basename(path) or os.path.basename(parent) != channel_id:
+            continue
+        if os.path.basename(os.path.dirname(parent)) != "attachments":
+            continue
+        if first_dir is not None and parent != first_dir:
+            continue
+        sniffed = _sniff_file(path)
+        if sniffed is None or sniffed != mime.lower():
+            continue
+        if first_dir is None:
+            first_dir = parent
+        kept.append((path, sniffed))
+    return kept, len(raw) - len(kept)
+
+
+def inbound_attachments(frame: dict) -> List[Tuple[str, str]]:
+    """Validated (path, sniffed mime) pairs from a daemon `message` frame."""
+    return scan_inbound_attachments(frame)[0]
+
+
 class ChannelStatusManager:
     """Per-channel working/idle status emitter, decoupled from any one reply
     turn (unlike openclaw-entry.js's inline reportStatus("working")/("idle")