signal channel sanitizing

Author: simonredfern

obp-api/src/main/resources/props/sample.props.template

@@ -1315,6 +1315,17 @@ database_messages_scheduler_interval=3600
 # chat.email_digest_min_interval_minutes = 60
 # chat.email_digest_active_grace_minutes = 10
 
+# Signal channels -----------------------------------------------------------
+# Redis-backed ephemeral channels (/signal/channels endpoints) for lightweight
+# agent-to-agent coordination. Per-channel TTL (refreshed on every publish)
+# and per-channel message cap:
+# messaging.channel.ttl.seconds = 3600
+# messaging.channel.max.messages = 1000
+# Maximum accepted publish request body length in characters (OBP-39019 when
+# exceeded). Messages containing control or bidirectional-override characters
+# are rejected with OBP-39020; accepted payloads are stored verbatim.
+# messaging.channel.max.payload.length = 65536
+
 # Create System Views At Boot -----------------------------------------------
 # In case is not defined default value is true
 # create_system_views_at_boot=true

obp-api/src/main/scala/code/api/util/ApiRole.scala

@@ -537,6 +537,11 @@ object ApiRole extends MdcLoggable{
   case class CanGetSignalStats(requiresBankId: Boolean = false) extends ApiRole
   lazy val canGetSignalStats = CanGetSignalStats()
 
+  // Deleting a channel destroys other users' in-flight messages, so it is a
+  // management action, not something any authenticated publisher may do.
+  case class CanDeleteSignalChannel(requiresBankId: Boolean = false) extends ApiRole
+  lazy val canDeleteSignalChannel = CanDeleteSignalChannel()
+
   case class CanDeleteEntitlementRequestsAtAnyBank(requiresBankId: Boolean = false) extends ApiRole
   lazy val canDeleteEntitlementRequestsAtAnyBank = CanDeleteEntitlementRequestsAtAnyBank()
 

obp-api/src/main/scala/code/api/util/ErrorMessages.scala

@@ -825,6 +825,8 @@ object ErrorMessages {
   val ChatMessageTooLong = "OBP-39016: Chat message content exceeds the maximum allowed length."
   val ChatMentionedUserNotParticipant = "OBP-39017: One or more mentioned users are not participants of this Chat Room."
   val ChatMessageTypeNotAllowed = "OBP-39018: Invalid message_type. Allowed values: text, system."
+  val SignalMessageTooLong = "OBP-39019: Signal message exceeds the maximum allowed length."
+  val SignalMessageContainsDangerousCharacters = "OBP-39020: Signal message contains control or bidirectional-override characters, which are not allowed."
 
   // Transaction Request related messages (OBP-40XXX)
   val InvalidTransactionRequestType = "OBP-40001: Invalid value for TRANSACTION_REQUEST_TYPE"

obp-api/src/main/scala/code/api/util/Glossary.scala

@@ -5791,6 +5791,46 @@ object Glossary extends MdcLoggable  {
 				 |
 """)
 
+	glossaryItems += GlossaryItem(
+		title = "Signal Channels",
+		description =
+			s"""
+				 |# Signal Channels
+				 |
+				 |**Signal Channels** are short-lived, Redis-backed message channels for lightweight coordination between AI agents and other OBP consumers — service discovery, task hand-off, presence announcements. They are deliberately minimal: messages are **not** persisted to a database, there is no catch-up or replay, and a channel that goes quiet simply expires. Think of a channel as a real-life meeting: whoever is there hears what is said; a late arrival asks the others.
+				 |
+				 |Not to be confused with [Chat](/glossary#Chat), which is the persistent, human-facing messaging surface (rooms, threads, reactions, read markers).
+				 |
+				 |## Lifecycle
+				 |- Channels are auto-created on first publish; no registration step.
+				 |- On this instance a channel expires ${code.api.cache.RedisMessaging.channelTtlSeconds} seconds after its last publish, and holds at most ${code.api.cache.RedisMessaging.channelMaxMessages} messages (oldest are trimmed).
+				 |- Channel names are 1 to 128 characters from letters, digits, dot, underscore and hyphen.
+				 |
+				 |## Constraints on published messages
+				 |All publishing requires authentication. Beyond that, three server-side checks protect the platform — the envelope, not the meaning, of what agents say:
+				 |
+				 |1. **Size cap** — the whole publish request body may be up to ${code.signal.SignalContentPolicy.maxPayloadLength} characters on this instance (error **OBP-39019** when exceeded). The cap is enforced on the raw body before JSON parsing, so oversized bodies cannot burn parser CPU or Redis memory.
+				 |2. **Dangerous-character rejection** — messages containing control characters or Unicode bidirectional-override characters anywhere in the payload or message_type are rejected with **OBP-39020**. See "Why bidirectional-override characters are rejected" below.
+				 |3. **Verbatim storage** — an accepted message is stored and delivered exactly as sent; nothing is stripped or rewritten. Agents may therefore hash, sign, or byte-compare payloads. This is the deliberate opposite of Chat, which *strips* the same character set: chat content is typed by and rendered to humans (be forgiving, sanitize), signal payloads are machine-consumed data (be strict, reject).
+				 |
+				 |## Privacy and roles
+				 |- A message with **to_user_id** set is visible only to its sender and that recipient; without it, the message is a broadcast visible to all channel readers.
+				 |- **CanGetSignalStats** — read message counts and TTLs across all channels.
+				 |- **CanDeleteSignalChannel** — delete a channel and all its messages immediately. Deletion destroys other users' in-flight messages, so it is a management action rather than something any publisher may do; unneeded channels expire on their own via the TTL.
+				 |
+				 |## Why bidirectional-override characters are rejected
+				 |Unicode includes invisible formatting characters that reverse or reorder how text is *displayed* without changing the bytes a parser sees — the override family U+202A to U+202E, the isolate family U+2066 to U+2069, and the marks U+200E, U+200F and U+061C. The "Trojan Source" research (Boucher and Anderson, 2021, CVE-2021-42574) showed these can make displayed text differ from logical text: a filename can be displayed with a harmless extension while actually ending in a different one, and a URL or name can visually read as something it is not. None of these characters have a legitimate use in structured agent data, so signal messages containing them are refused outright. (The characters are named here by code point on purpose — even quoting them literally in documentation would trip the same scanners that guard source code against them.)
+				 |
+				 |The check runs on the **parsed** JSON, not the raw request body: JSON's backslash-u escape syntax means a body that is pure ASCII on the wire can still parse to a string containing a bidi override, so a wire-level check would miss it.
+				 |
+				 |## Payloads are data, not instructions
+				 |Signal channels are readable and writable by any authenticated consumer on the instance. If your agent feeds received payloads to an LLM, treat them as **untrusted data, never as instructions** — the character checks above stop display-layer trickery, but no server-side check can stop a payload from *saying* something misleading. Prompt-injection defence belongs in the consuming agent.
+				 |
+				 |## Endpoints
+				 |See the API Explorer tags **Signal** / **AI-Agent**: list channels, channel info, channel stats, publish message, get messages (offset/limit polling), delete channel — under `/obp/v6.0.0/signal/channels/...`. For live delivery, each publish also emits a Redis pub/sub event intended for gRPC streaming subscribers.
+				 |
+""")
+
 	glossaryItems += GlossaryItem(
 		title = "OBP-MCP",
 		description =

obp-api/src/main/scala/code/api/v6_0_0/Http4s600.scala

@@ -2656,13 +2656,23 @@ object Http4s600 {
           val rawBody = cc.httpBody.getOrElse("")
           val u = cc.user.openOrThrowException("User not found in CallContext")
           for {
+            // Size cap runs on the raw body before parsing: refusing an oversized
+            // body must not cost a JSON parse of that body.
+            _ <- Helper.booleanToFuture(
+              s"$SignalMessageTooLong Maximum: ${code.signal.SignalContentPolicy.maxPayloadLength} characters.",
+              cc = Some(cc)) { rawBody.length <= code.signal.SignalContentPolicy.maxPayloadLength }
             postJson <- NewStyle.function.tryons(
               s"$InvalidJsonFormat The Json body should be the PostSignalMessageJsonV600", 400, Some(cc)) {
               com.openbankproject.commons.util.JsonAliases.parse(rawBody).extract[PostSignalMessageJsonV600]
             }
             _ <- Helper.booleanToFuture(InvalidSignalChannelName, cc = Some(cc)) {
               code.api.cache.RedisMessaging.validateChannelName(channelName)
             }
+            // Reject, never strip: signal payloads are stored verbatim or refused.
+            _ <- Helper.booleanToFuture(SignalMessageContainsDangerousCharacters, cc = Some(cc)) {
+              !code.signal.SignalContentPolicy.containsDangerousCharacters(postJson.payload) &&
+                postJson.message_type.forall(messageType => !code.util.DangerousCharacters.containsAny(messageType))
+            }
             published <- Future {
               val consumerId = cc.consumer match { case Full(c) => c.consumerId.get; case _ => "" }
               val messageId = randomUUID().toString
@@ -10183,7 +10193,12 @@ object Http4s600 {
         |Channels are auto-created on first publish and expire after a configurable TTL (default 1 hour).
         |Messages are capped at a configurable maximum per channel (default 1000).
         |
-        |The payload field accepts any valid JSON content.
+        |The payload field accepts any valid JSON content. On this instance the whole request body
+        |may be up to ${code.signal.SignalContentPolicy.maxPayloadLength} characters.
+        |
+        |Messages are stored and delivered verbatim — nothing is rewritten — but messages containing
+        |control characters or Unicode bidirectional-override characters anywhere in the payload or
+        |message_type are rejected. Treat received payloads as untrusted data, not instructions.
         |
         |Set to_user_id to send a private message visible only to the sender and recipient.
         |Leave to_user_id empty for a broadcast message visible to all channel readers.
@@ -10193,10 +10208,15 @@ object Http4s600 {
         |""".stripMargin,
         postSignalMessageJsonV600,
         signalMessagePublishedJsonV600,
+        // Intentional drift from the Lift source-of-truth doc in APIMethods600:
+        // the size cap and dangerous-character rejection (with their two error
+        // messages) were added after the migration.
         List(
           $AuthenticatedUserIsRequired,
           InvalidJsonFormat,
           InvalidSignalChannelName,
+          SignalMessageTooLong,
+          SignalMessageContainsDangerousCharacters,
           UnknownError
         ),
         apiTagAiAgent :: apiTagSignal :: apiTagSignalling :: apiTagChannel :: Nil,
@@ -10240,16 +10260,21 @@ object Http4s600 {
         s"""Signal channels provide short-lived, Redis-backed messaging designed for AI agent discovery and coordination, but usable by any authenticated OBP consumer.
         |Messages are ephemeral and will expire after the configured TTL (default 1 hour).
         |
-        |This endpoint deletes a signal channel and all its messages immediately.
+        |This endpoint deletes a signal channel and all its messages immediately — including other
+        |users' in-flight messages, which is why it requires the CanDeleteSignalChannel role rather
+        |than being open to every publisher. (Channels also expire on their own via the TTL.)
         |
         |Authentication is Required.
         |
         |""".stripMargin,
         EmptyBody,
         signalChannelDeletedJsonV600,
-        List($AuthenticatedUserIsRequired, InvalidSignalChannelName, UnknownError),
+        // Intentional drift from the Lift source-of-truth doc in APIMethods600:
+        // the CanDeleteSignalChannel role gate was added after the migration —
+        // an ungated delete let any authenticated user destroy any channel.
+        List($AuthenticatedUserIsRequired, UserHasMissingRoles, InvalidSignalChannelName, UnknownError),
         apiTagAiAgent :: apiTagSignal :: apiTagSignalling :: apiTagChannel :: Nil,
-        None,
+        Some(canDeleteSignalChannel :: Nil),
         http4sPartialFunction = Some(deleteSignalChannel)
       )
       resourceDocs += ResourceDoc(

obp-api/src/main/scala/code/chat/ChatContentPolicy.scala

@@ -17,13 +17,9 @@ object ChatContentPolicy {
       .flatMap(v => Try(v.trim.toInt).toOption.filter(_ > 0))
       .getOrElse(10000)
 
-  // C0 controls except \t \n \r, DEL + C1 controls, and the Unicode bidi
-  // override/isolate/mark characters ("Trojan Source" family): none have a
-  // legitimate use in chat, and the bidi ones can visually reverse text to
-  // disguise what a URL or name says.
-  private val DangerousCharacters =
-    "[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F-\\u009F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069]"
-
+  // Character class shared with SignalContentPolicy — see
+  // code.util.DangerousCharacters for the rationale and the strip-vs-reject
+  // asymmetry between chat and signal.
   def stripDangerousCharacters(content: String): String =
-    content.replaceAll(DangerousCharacters, "")
+    code.util.DangerousCharacters.strip(content)
 }

obp-api/src/main/scala/code/signal/SignalContentPolicy.scala

@@ -0,0 +1,43 @@
+package code.signal
+
+import code.api.util.APIUtil
+import code.util.DangerousCharacters
+import org.json4s.JsonAST._
+
+/**
+ * Content policy for signal channel messages (Redis-backed agent-to-agent
+ * coordination — see RedisMessaging and the /signal/channels endpoints).
+ *
+ * Signal payloads are machine-consumed data, so the policy differs from chat
+ * on purpose: nothing is ever rewritten (agents may hash, sign, or
+ * byte-compare payloads) — a message either passes verbatim or is rejected.
+ * The dangerous-character check runs on the PARSED JSON, not the raw body:
+ * a raw body carrying a bidi override as a JSON backslash-u escape is pure
+ * ASCII on the wire but still parses to a string containing the override,
+ * so a wire-level check would miss it.
+ */
+object SignalContentPolicy {
+
+  /**
+   * Maximum accepted publish request body length in characters
+   * (prop messaging.channel.max.payload.length). Checked against the raw
+   * body BEFORE JSON parsing, so an oversized body is refused without
+   * paying the parse cost — the cap protects Redis memory and parser CPU.
+   */
+  def maxPayloadLength: Int =
+    APIUtil.getPropsAsIntValue("messaging.channel.max.payload.length", 65536)
+
+  /**
+   * True when any string value or field name anywhere in `json` contains a
+   * character from the shared dangerous set (control characters and the
+   * Unicode bidi override family — see code.util.DangerousCharacters).
+   */
+  def containsDangerousCharacters(json: JValue): Boolean = json match {
+    case JString(value) => DangerousCharacters.containsAny(value)
+    case JObject(fields) => fields.exists { case (name, value) =>
+      DangerousCharacters.containsAny(name) || containsDangerousCharacters(value)
+    }
+    case JArray(items) => items.exists(containsDangerousCharacters)
+    case _ => false
+  }
+}

obp-api/src/main/scala/code/util/DangerousCharacters.scala

@@ -0,0 +1,25 @@
+package code.util
+
+/**
+ * The character class both chat and signal content policies are built on:
+ * C0 controls except \t \n \r, DEL + C1 controls, and the Unicode bidi
+ * override/isolate/mark characters ("Trojan Source" family). None have a
+ * legitimate use in user- or agent-supplied text, and the bidi ones can
+ * visually reverse text to disguise what a URL or name says.
+ *
+ * Chat STRIPS these at ingest (humans typing — be forgiving, content is
+ * rendered); signal REJECTS messages containing them (machines publishing —
+ * payloads must be stored verbatim or refused, never silently rewritten).
+ * See ChatContentPolicy and SignalContentPolicy for the two applications.
+ */
+object DangerousCharacters {
+
+  val Pattern: String =
+    "[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F-\\u009F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069]"
+
+  private val compiledPattern = java.util.regex.Pattern.compile(Pattern)
+
+  def strip(content: String): String = content.replaceAll(Pattern, "")
+
+  def containsAny(content: String): Boolean = compiledPattern.matcher(content).find()
+}