From b8004a28cc5893952c2e6029d678e4a3cfa63186 Mon Sep 17 00:00:00 2001 From: Shrinija Kummari Date: Wed, 4 Feb 2026 21:05:16 -0800 Subject: [PATCH] docs: improve DM security guidance with concrete example Add a more prominent security warning for multi-user DM setups: - Add blockquote security warning about context leakage - Include concrete example showing the privacy risk - Add "When to enable this" checklist - Clarify that default is fine for single-user setups Co-Authored-By: Claude Opus 4.5 --- docs/concepts/session.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 6d4afc7e4..8ff07e86b 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -17,9 +17,17 @@ Use `session.dmScope` to control how **direct messages** are grouped: - `per-account-channel-peer`: isolate by account + channel + sender (recommended for multi-account inboxes). Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`. -### Secure DM mode (recommended) +### Secure DM mode (recommended for multi-user setups) -If your agent can receive DMs from **multiple people** (pairing approvals for more than one sender, a DM allowlist with multiple entries, or `dmPolicy: "open"`), enable **secure DM mode** to avoid cross-user context leakage: +> **Security Warning:** If your agent can receive DMs from **multiple people**, you should enable secure DM mode. Without it, all users share the same conversation context, which can leak private information between users. + +**Example of the problem with default settings:** + +- User A (+1555) messages your agent about their medical appointment +- User B (+2666) messages your agent asking "What were we talking about?" +- User B sees User A's private medical information because they share the same session + +**The fix:** Set `dmScope` to isolate sessions per user: ```json5 // ~/.openclaw/openclaw.json @@ -31,9 +39,16 @@ If your agent can receive DMs from **multiple people** (pairing approvals for mo } ``` +**When to enable this:** + +- You have pairing approvals for more than one sender +- You use a DM allowlist with multiple entries +- You set `dmPolicy: "open"` +- Multiple phone numbers or accounts can message your agent + Notes: -- Default is `dmScope: "main"` for continuity (all DMs share the main session). +- Default is `dmScope: "main"` for continuity (all DMs share the main session). This is fine for single-user setups. - For multi-account inboxes on the same channel, prefer `per-account-channel-peer`. - If the same person contacts you on multiple channels, use `session.identityLinks` to collapse their DM sessions into one canonical identity.