From 3816487bec64b2f6414bb9c92e580017255a2d2b Mon Sep 17 00:00:00 2001
From: "david.delagneau" <david@all-win.software>
Date: Tue, 19 May 2026 16:15:48 -0600
Subject: [PATCH] feat: update Mattermost proxy configuration and documentation
 for improved clarity and default behavior

---
 scripts/mattermost-proxy/.env.example         |  5 +--
 scripts/mattermost-proxy/README.md            | 31 ++++++++++++++++++-
 scripts/mattermost-proxy/mattermost_mirror.py |  6 +++-
 scripts/mattermost-proxy/run-mirror.sh        |  3 ++
 4 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/scripts/mattermost-proxy/.env.example b/scripts/mattermost-proxy/.env.example
index 32abb2b..a45dede 100644
--- a/scripts/mattermost-proxy/.env.example
+++ b/scripts/mattermost-proxy/.env.example
@@ -1,8 +1,9 @@
 # Mattermost proxy mirror configuration.
 # Copy to .env if you want local overrides. Do not commit .env.
 
-# Restrict capture to the Mattermost host. Use the host only, no scheme.
-# Example: mattermost.example.com
+# Optional: restrict capture to the Mattermost host. Use the host only, no scheme.
+# If empty, the addon captures /api/v4 traffic from the proxied Mattermost app.
+# Example: mm.all-win-solutions.app
 MATTERMOST_MIRROR_HOST_ALLOW=
 
 # Output directory for raw evidence and normalized AI-readable context.
diff --git a/scripts/mattermost-proxy/README.md b/scripts/mattermost-proxy/README.md
index e719b5e..80be7a2 100644
--- a/scripts/mattermost-proxy/README.md
+++ b/scripts/mattermost-proxy/README.md
@@ -15,7 +15,7 @@ Mattermost Team Edition 11.4.2 exposes normal `/api/v4` REST and WebSocket traff
    - Start `scripts/mattermost-proxy/run-mirror.sh`
    - Open `http://mitm.it`
    - Install/trust the certificate in Keychain.
-3. Optional: copy `.env.example` to `.env` and set `MATTERMOST_MIRROR_HOST_ALLOW` to the exact Mattermost host.
+3. Optional: copy `.env.example` to `.env` and set `MATTERMOST_MIRROR_HOST_ALLOW` to the exact Mattermost host, for example `mm.all-win-solutions.app`.
 
 ## Run day to day
 
@@ -101,3 +101,32 @@ Each line in the normalized JSONL contains:
 - `MATTERMOST_MIRROR_CHANNEL_IDS`: optional comma-separated channel ID allowlist.
 - `MATTERMOST_MIRROR_WRITE_RAW`: set to `1` to save compact raw REST/WebSocket evidence.
 - `MATTERMOST_APP_PATH`: Mattermost Desktop `.app` bundle path.
+
+## Troubleshooting
+
+### TLS certificate warnings
+
+Mitmproxy uses a persistent local CA under `~/.mitmproxy`. If the desktop app
+asks about the certificate after every proxy restart, install and trust that CA
+in macOS Keychain instead of approving it only in the app prompt:
+
+1. Start `scripts/mattermost-proxy/run-mirror.sh`.
+2. Open `http://mitm.it` from a browser on this Mac and download the macOS certificate.
+3. Add it to Keychain Access and set it to **Always Trust**.
+4. Restart Mattermost Desktop through `launch-mattermost.sh`.
+
+Warnings for unrelated hosts such as `releases.mattermost.com` or OpenGraph
+preview hosts are not required for message capture. The mirror only writes
+normalized messages from Mattermost `/api/v4` REST/WebSocket payloads.
+
+### Proxy logs show traffic but no `latest.md`
+
+The mirror writes files only after it sees a post payload. Startup calls such as
+`/api/v4/teams`, `/api/v4/users`, `/api/v4/files`, or WebSocket ping/ack events
+do not create message files. Open a channel, open a thread, scroll slightly in
+history, or wait for/send a new message. Then check:
+
+```text
+ai/inbox/mattermost-mirror/latest.md
+ai/inbox/mattermost-mirror/messages/YYYY/MM/YYYY-MM-DD.jsonl
+```
diff --git a/scripts/mattermost-proxy/mattermost_mirror.py b/scripts/mattermost-proxy/mattermost_mirror.py
index 61f96b3..1af4e90 100644
--- a/scripts/mattermost-proxy/mattermost_mirror.py
+++ b/scripts/mattermost-proxy/mattermost_mirror.py
@@ -147,7 +147,11 @@ class MattermostMirror:
         host = host.lower()
         if self.host_allow:
             return host == self.host_allow or host.endswith(f".{self.host_allow}")
-        return "mattermost" in host
+        # The launched Mattermost Desktop app is already scoped to this proxy.
+        # Some company hosts do not include "mattermost" in the hostname
+        # (for example, mm.example.com), so default to allowing the proxied
+        # app's /api/v4 traffic when no explicit host allowlist is configured.
+        return True
 
     def _is_allowed_channel(self, channel_id: str | None) -> bool:
         if not self.channel_allow:
diff --git a/scripts/mattermost-proxy/run-mirror.sh b/scripts/mattermost-proxy/run-mirror.sh
index 9ad7cc7..c91cd32 100755
--- a/scripts/mattermost-proxy/run-mirror.sh
+++ b/scripts/mattermost-proxy/run-mirror.sh
@@ -20,6 +20,9 @@ mkdir -p "$MATTERMOST_MIRROR_DIR"
 echo "Mattermost proxy mirror output: $MATTERMOST_MIRROR_DIR"
 echo "Listening on ${MATTERMOST_MIRROR_LISTEN_HOST}:${MATTERMOST_MIRROR_LISTEN_PORT}"
 echo "Launch Mattermost Desktop with: scripts/mattermost-proxy/launch-mattermost.sh"
+if [ -z "${MATTERMOST_MIRROR_HOST_ALLOW:-}" ]; then
+  echo "MATTERMOST_MIRROR_HOST_ALLOW is not set; capturing /api/v4 traffic from the proxied app."
+fi
 
 exec mitmdump \
   --listen-host "$MATTERMOST_MIRROR_LISTEN_HOST" \