Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(config): MESSAGING_PUBLIC_URL, separate from the gateway's public origin

Petr Baucha25a5d3d8415
diff --git a/.env.example b/.env.example
index ed7a9c2f4..545f48d63 100644
--- a/.env.example
+++ b/.env.example
@@ -121,6 +121,20 @@ FRONTEND_BASE_URL=http://localhost:5173
# deeplink.
# GATEWAY_PUBLIC_URL=http://localhost:8000
+# Public origin a messaging platform reaches Switch on: the base of the OAuth
+# redirect and the event URLs under /messaging for the distributed Slack app.
+# Must be https and must resolve from the internet, so it is usually a
+# different host from GATEWAY_PUBLIC_URL. Required to offer workspace installs.
+# MESSAGING_PUBLIC_URL=https://switch.example.com
+
+# Credentials of the distributed Slack app — the one a customer installs by
+# clicking a button, not the one an operator registers for themselves (that is
+# SLACK_BOT_TOKEN et al). Set all three or none; setting some is refused at
+# startup. See docs/old/bridges/SLACK_DISTRIBUTED_APP.md.
+# SLACK_APP_CLIENT_ID=
+# SLACK_APP_CLIENT_SECRET=
+# SLACK_APP_SIGNING_SECRET=
+
# ── Mattermost (local dev) ───────────────────────────────────────────────────
MATTERMOST_ADMIN_USER=admin
MATTERMOST_ADMIN_PASSWORD=
diff --git a/core/switch_core/bridges/collaboration/install.py b/core/switch_core/bridges/collaboration/install.py
index 62b7012a8..8abdcffee 100644
--- a/core/switch_core/bridges/collaboration/install.py
+++ b/core/switch_core/bridges/collaboration/install.py
@@ -71,8 +71,8 @@ def commands_path(platform: str) -> str:
def public_url(public_origin: str, path: str) -> str:
"""Absolute URL for one install path, given the deployment's public origin.
- The origin is `GATEWAY_PUBLIC_URL`, which is validated at startup as scheme
- and host with no path, so this is a join and not a merge. It exists as a
+ The origin is `MESSAGING_PUBLIC_URL`, which is validated at startup as
+ scheme and host with no path, so this is a join and not a merge. It exists as a
function so the redirect URI sent to the platform and the one registered
with the app are built the same way — the platform compares them exactly,
and a trailing slash on one side is a refused install with a message that
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index 93683bbd9..1881292a4 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -194,6 +194,20 @@ class SwitchConfig(BaseSettings):
slack_app_client_secret: str | None = None
slack_app_signing_secret: str | None = None
+ # Public origin (scheme + host, no path) that a messaging platform reaches
+ # Switch on: the base of the OAuth redirect and of the three event URLs
+ # under `/messaging`, and the one registered with the app.
+ #
+ # Separate from `gateway_public_url` because the two answer to different
+ # audiences and need not be the same host. The gateway URL is opened by a
+ # person following a deeplink and may live on a private network; this one
+ # is dialled by Slack from the internet and must resolve and present a
+ # browser-trusted certificate there. A deployment whose gateway is
+ # reachable only over a VPN can still offer installs, and pointing the
+ # gateway URL at the internet-facing host to achieve that would silently
+ # move every deeplink along with it.
+ messaging_public_url: str | None = None
+
# Upper bound on a single attachment an agent may post to a room (and that
# a collaboration bridge will relay out). Uploads over this raise instead
# of being truncated or silently dropped.
@@ -410,6 +424,28 @@ class SwitchConfig(BaseSettings):
)
return self
+ @model_validator(mode="after")
+ def _validate_messaging_public_url(self) -> "SwitchConfig":
+ # Slack compares the redirect URI it is sent against the one registered
+ # with the app, byte for byte, and reports a mismatch as a generic
+ # refusal. A path here would make every install URL wrong in a way the
+ # error message does not name, so it is a startup error instead.
+ if self.messaging_public_url:
+ parts = urlsplit(self.messaging_public_url)
+ if not parts.scheme or not parts.netloc or parts.path not in ("", "/"):
+ raise ValueError(
+ "MESSAGING_PUBLIC_URL must be a scheme + host only "
+ "(e.g. https://switch.example), with no path, "
+ f"got {self.messaging_public_url!r}."
+ )
+ if parts.scheme != "https":
+ raise ValueError(
+ "MESSAGING_PUBLIC_URL must be https. Slack refuses to "
+ "register an http redirect or event URL, so an http origin "
+ f"cannot work, got {self.messaging_public_url!r}."
+ )
+ return self
+
@model_validator(mode="after")
def _validate_gateway_oidc(self) -> "SwitchConfig":
required = (
@@ -456,9 +492,9 @@ class SwitchConfig(BaseSettings):
# the app. Without the origin they would be built against nothing, so a
# deployment configured to offer installs and unable to name itself is
# a startup error rather than a broken button.
- if set_count and not self.gateway_public_url:
+ if set_count and not self.messaging_public_url:
raise ValueError(
- "A distributed Slack app is configured but GATEWAY_PUBLIC_URL "
+ "A distributed Slack app is configured but MESSAGING_PUBLIC_URL "
"is not. The install redirect and the events endpoint are built "
"from it, and Slack rejects a redirect that does not match the "
"one registered with the app."
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index f36744ffc..067e995d5 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -502,13 +502,13 @@ async def run(config: SwitchConfig) -> None:
install_service: MessagingInstallService | None = None
if installers.platforms():
- assert config.gateway_public_url is not None
+ assert config.messaging_public_url is not None
install_service = MessagingInstallService(
session_factory=session_factory,
store=MessagingInstallStore(),
installers=installers,
lifecycle=collab_lifecycle,
- public_origin=config.gateway_public_url,
+ public_origin=config.messaging_public_url,
secret=config.jwt_secret_key,
)
diff --git a/core/tests/switch_core/test_config_slack_app.py b/core/tests/switch_core/test_config_slack_app.py
index 5c9c18222..603bd1f45 100644
--- a/core/tests/switch_core/test_config_slack_app.py
+++ b/core/tests/switch_core/test_config_slack_app.py
@@ -41,7 +41,7 @@ def test_setting_none_of_them_is_the_ordinary_case() -> None:
def test_setting_all_three_with_a_public_origin_is_accepted() -> None:
- config = _config(**_APP, gateway_public_url="https://switch.example")
+ config = _config(**_APP, messaging_public_url="https://switch.example")
assert config.slack_app_signing_secret == "signing"
@@ -49,7 +49,7 @@ def test_setting_all_three_with_a_public_origin_is_accepted() -> None:
def test_setting_some_of_them_raises(missing: str) -> None:
partial = {key: value for key, value in _APP.items() if key != missing}
with pytest.raises(ValueError, match="Partial distributed Slack app config"):
- _config(**partial, gateway_public_url="https://switch.example")
+ _config(**partial, messaging_public_url="https://switch.example")
def test_an_app_with_no_public_origin_raises() -> None:
@@ -59,5 +59,36 @@ def test_an_app_with_no_public_origin_raises() -> None:
building it against nothing is an install that fails at Slack with nothing
in our logs.
"""
- with pytest.raises(ValueError, match="GATEWAY_PUBLIC_URL"):
+ with pytest.raises(ValueError, match="MESSAGING_PUBLIC_URL"):
_config(**_APP)
+
+
+def test_the_gateway_url_does_not_stand_in_for_it() -> None:
+ """They name different hosts and only one of them is dialled by Slack.
+
+ A deployment whose gateway is on a private network is the ordinary case,
+ and accepting that value here would register a redirect URL Slack cannot
+ reach — an install that fails at Slack with nothing in our logs.
+ """
+ with pytest.raises(ValueError, match="MESSAGING_PUBLIC_URL"):
+ _config(**_APP, gateway_public_url="https://gateway.example")
+
+
+def test_a_path_on_the_origin_is_refused() -> None:
+ """Slack compares the redirect byte for byte and says only that it failed."""
+ with pytest.raises(ValueError, match=r"scheme \+ host only"):
+ _config(**_APP, messaging_public_url="https://switch.example/messaging")
+
+
+def test_a_trailing_slash_is_allowed() -> None:
+ """The one path that is harmless: joining it with a rooted path is the same
+ string either way, and an operator who pastes a host with one should not be
+ refused for it."""
+ config = _config(**_APP, messaging_public_url="https://switch.example/")
+ assert config.messaging_public_url == "https://switch.example/"
+
+
+def test_an_http_origin_is_refused() -> None:
+ """Slack will not register one, so accepting it only defers the failure."""
+ with pytest.raises(ValueError, match="must be https"):
+ _config(**_APP, messaging_public_url="http://switch.example")
diff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.yml
index f9ec593e0..9ff50cde2 100644
--- a/deploy/local/standalone-docker-compose.yml
+++ b/deploy/local/standalone-docker-compose.yml
@@ -207,6 +207,10 @@ services:
GATEWAY_ADMIN_PASSWORD: ${GATEWAY_ADMIN_PASSWORD}
FRONTEND_BASE_URL: ${FRONTEND_BASE_URL}
GATEWAY_PUBLIC_URL: ${GATEWAY_PUBLIC_URL:-}
+ MESSAGING_PUBLIC_URL: ${MESSAGING_PUBLIC_URL:-}
+ SLACK_APP_CLIENT_ID: ${SLACK_APP_CLIENT_ID:-}
+ SLACK_APP_CLIENT_SECRET: ${SLACK_APP_CLIENT_SECRET:-}
+ SLACK_APP_SIGNING_SECRET: ${SLACK_APP_SIGNING_SECRET:-}
depends_on:
postgres:
condition: service_healthy
diff --git a/docs/old/bridges/SLACK_DISTRIBUTED_APP.md b/docs/old/bridges/SLACK_DISTRIBUTED_APP.md
index 04d6e0f1f..d0e4f9da4 100644
--- a/docs/old/bridges/SLACK_DISTRIBUTED_APP.md
+++ b/docs/old/bridges/SLACK_DISTRIBUTED_APP.md
@@ -32,10 +32,16 @@ That is the whole of the difference, and everything below follows from it.
## The four URLs
-Every URL is the same host with a different path. The host is the public
-origin of the deployment — the same value as `GATEWAY_PUBLIC_URL`, which is
-already validated as scheme-and-host with no path and already serves the
-deeplink redirect from the same application.
+Every URL is the same host with a different path. The host is
+**`MESSAGING_PUBLIC_URL`**: scheme and host, no path, https only, and the
+origin Slack itself dials.
+
+It is deliberately not `GATEWAY_PUBLIC_URL`. That one is the host a *person*
+lands on following an "Open in Switch Console" deeplink, and on many
+deployments it is reachable only over a private network — which is fine for a
+person and useless to Slack. Pointing it at an internet-facing host to satisfy
+Slack would move every deeplink to that host as a side effect, so the two are
+separate settings and a deployment may set either, both, or neither.
| Slack setting | Path |
| --- | --- |