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(bridges): install protocol for the distributed Slack app (CHOO-2626)

Petr Baucha74ed64292de
diff --git a/core/switch_core/bridges/agent/auth.py b/core/switch_core/bridges/agent/auth.py
index fac0bb763..5fa9a4f11 100644
--- a/core/switch_core/bridges/agent/auth.py
+++ b/core/switch_core/bridges/agent/auth.py
@@ -12,6 +12,9 @@ from starlette.types import ASGIApp, Receive, Scope, Send
from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.bridges.agent.registration_bootstrap import REGISTRATION_KEY_TYPES
+from switch_core.bridges.collaboration.install import (
+ PUBLIC_PATH_PREFIX as MESSAGING_INSTALL_PREFIX,
+)
from switch_core.db.models import Agent, ApiKey
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.agent_store import AgentStore
@@ -37,6 +40,11 @@ PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
# Public switchdash:// deeplink HTTP redirect — followed by whoever clicks
# the "Open in Switch Console" link in an external channel, so no bearer token.
"/deeplink",
+ # Workspace installs of the distributed messaging apps: the OAuth callback
+ # and the platforms' event webhooks. Unauthenticated by nature — an inbound
+ # Slack event carries no credential of ours — so each route proves its own
+ # origin from the platform's signature before it does anything else.
+ MESSAGING_INSTALL_PREFIX,
)
diff --git a/core/switch_core/bridges/collaboration/install.py b/core/switch_core/bridges/collaboration/install.py
new file mode 100644
index 000000000..ff9e4039e
--- /dev/null
+++ b/core/switch_core/bridges/collaboration/install.py
@@ -0,0 +1,220 @@
+"""Installing *our* app into someone else's workspace.
+
+A `CollaborationAdapter` is what a bridge runs; this is what happens before
+there is one. The distinction is not organisational — the two have genuinely
+different lifetimes and genuinely different secrets:
+
+- An adapter is per bridge, built from a `connection_config` that already
+ holds a working credential, and it exists only while that bridge runs.
+- An installer is per deployment, built once from the credentials of the app
+ *we* registered with the platform, and it exists whether or not any bridge
+ does. It is what turns a click on "Add to Slack" into a credential, and what
+ proves an inbound webhook came from the platform rather than from anyone who
+ found the URL.
+
+So an installer is not a classmethod on the adapter. Making it one would mean
+threading a client secret through every call, and would put "which app did we
+register with Slack" on an object whose whole scope is one customer's bridge.
+
+**The seam between the two is `connection_config`.** An installer's last act
+is to render the grant into exactly the dict the platform's adapter already
+takes, so nothing downstream of the install knows an install happened:
+`CollaborationBridgeLifecycleService.register` validates and starts it the way
+it does a bridge an operator typed in by hand. That is deliberate — an
+installed bridge and a self-registered one differ in where the token came
+from, and in nothing else.
+
+**Registration is the feature flag.** There is no `installs_enabled` setting.
+An installer exists for a platform when that platform's app credentials are
+configured, and the endpoints refuse when it does not — a deployment that has
+not registered an app cannot half-offer installs.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+#: The public prefix every install endpoint hangs off.
+#:
+#: Its own prefix rather than a corner of an existing one, because everything
+#: under it is unauthenticated by nature — a Slack event carries no credential
+#: of ours, and a callback arrives before there is anything to authenticate
+#: against. Grouping them makes that one property of the prefix rather than of
+#: each route.
+#:
+#: Deliberately not under `/gateway`, which is cookie-authenticated and is not
+#: routed to this application from outside; and deliberately not under
+#: `/oauth`, which already belongs to agents authenticating *to* Switch and
+#: would share only the word.
+PUBLIC_PATH_PREFIX = "/messaging"
+
+
+def oauth_callback_path(platform: str) -> str:
+ return f"{PUBLIC_PATH_PREFIX}/{platform}/oauth/callback"
+
+
+def events_path(platform: str) -> str:
+ return f"{PUBLIC_PATH_PREFIX}/{platform}/events"
+
+
+def interactive_path(platform: str) -> str:
+ return f"{PUBLIC_PATH_PREFIX}/{platform}/interactive"
+
+
+def commands_path(platform: str) -> str:
+ return f"{PUBLIC_PATH_PREFIX}/{platform}/commands"
+
+
+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
+ 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
+ does not say so.
+ """
+ return f"{public_origin.rstrip('/')}{path}"
+
+
+class MessagingInstallError(RuntimeError):
+ """An install could not be completed, with a reason fit to show an operator.
+
+ Raised rather than returned for the usual reason: every caller of these
+ methods is a request handler that must not continue on a failure, and a
+ falsy return is the kind of thing a caller forgets to check.
+ """
+
+
+class WebhookAuthenticityError(RuntimeError):
+ """An inbound webhook did not prove it came from the platform.
+
+ Separate from `MessagingInstallError` because the two are answered
+ differently: an install failure is shown to the operator who caused it,
+ while this one is a request from an unknown party and gets a bare 401 with
+ nothing in it. Never log the body alongside this — it is unauthenticated
+ input.
+ """
+
+
+@dataclass(frozen=True)
+class InstallGrant:
+ """What the platform handed back when a workspace installed us.
+
+ Deliberately three fields and not the platform's whole response. What a
+ grant *is*, across platforms, is a workspace, a credential, and the
+ permissions that credential was actually given — everything else in the
+ response is Slack's shape and belongs behind `connection_config`.
+
+ `scopes` is the platform's own spelling, kept verbatim. A scope string that
+ means nothing to us is still the thing to show an operator asking why a
+ call was refused, and parsing it into a list here would be a parser to keep
+ in step with someone else's vocabulary for no gain.
+ """
+
+ external_workspace_id: str
+ bot_token: str
+ scopes: str
+
+
+class MessagingAppInstaller(ABC):
+ """The install half of one platform, holding that platform's app credentials.
+
+ One instance per platform per deployment, built at boot from config and
+ registered by platform name. Every method is deliberately synchronous
+ except the code exchange, which is the only one that talks to the network.
+ """
+
+ #: The platform this installs, matching the adapter registry's key and the
+ #: `platform` column on `messaging_installs`.
+ platform: ClassVar[str]
+
+ @abstractmethod
+ def authorize_url(self, *, state: str, redirect_uri: str) -> str:
+ """Where to send the browser to begin an install.
+
+ `state` is opaque here and is not the installer's to interpret: it is
+ minted, signed and redeemed by the install service, and this method's
+ only obligation is to hand it back to the platform unchanged.
+ """
+
+ @abstractmethod
+ async def redeem(self, *, code: str, redirect_uri: str) -> InstallGrant:
+ """Exchange the authorization code the callback carried for a credential.
+
+ `redirect_uri` is passed again because the platform checks it matches
+ the one the flow started with — it is part of the proof, not a
+ convenience.
+
+ Raise :class:`MessagingInstallError` on anything short of a usable
+ grant, including a well-formed response the platform marked as failed.
+ """
+
+ @abstractmethod
+ def verify_webhook(self, *, headers: Mapping[str, str], body: bytes) -> None:
+ """Prove an inbound event came from the platform, or raise.
+
+ Takes the **raw body**, not a parsed payload, because every platform's
+ signature covers the bytes as sent: re-serialising a parsed dict
+ produces different bytes and a signature that never verifies.
+
+ This is the first thing any webhook handler does — before parsing,
+ before resolving a tenant, before logging the body. Raise
+ :class:`WebhookAuthenticityError`.
+ """
+
+ @abstractmethod
+ def workspace_of_event(self, payload: Mapping[str, object]) -> str:
+ """Which workspace an authenticated event came from.
+
+ The answer is what resolves a tenant, so this runs on a request with
+ nothing bound and must not touch the database. Raise
+ :class:`WebhookAuthenticityError` for a payload that names no
+ workspace: an event we cannot route is not an event we may guess at.
+ """
+
+ @abstractmethod
+ def connection_config(self, grant: InstallGrant) -> dict[str, object]:
+ """Render a grant as the connection config this platform's adapter takes.
+
+ The whole point of the abstraction: after this, an installed bridge is
+ indistinguishable from one an operator registered by hand, and every
+ line of lifecycle, validation and start-up code is shared.
+ """
+
+
+class MessagingInstallerRegistry:
+ """The installers this deployment has app credentials for.
+
+ A dict with a loud `__getitem__`, which is the only behaviour worth a class
+ here: asking for a platform nobody registered an app for is the ordinary
+ case (most deployments will register none), and it has to produce a
+ sentence an operator can act on rather than a `KeyError` in a traceback.
+ """
+
+ def __init__(self) -> None:
+ self._installers: dict[str, MessagingAppInstaller] = {}
+
+ def register(self, installer: MessagingAppInstaller) -> None:
+ if installer.platform in self._installers:
+ raise MessagingInstallError(
+ f"an installer for {installer.platform!r} is already registered"
+ )
+ self._installers[installer.platform] = installer
+
+ def get(self, platform: str) -> MessagingAppInstaller:
+ try:
+ return self._installers[platform]
+ except KeyError:
+ raise MessagingInstallError(
+ f"no {platform} app is registered with this deployment, so it "
+ "cannot be installed into a workspace. Configure the app's "
+ "credentials and restart."
+ ) from None
+
+ def platforms(self) -> list[str]:
+ return sorted(self._installers)
diff --git a/core/switch_core/bridges/collaboration/slack/adapter.py b/core/switch_core/bridges/collaboration/slack/adapter.py
index fb6beebfc..009b69da6 100644
--- a/core/switch_core/bridges/collaboration/slack/adapter.py
+++ b/core/switch_core/bridges/collaboration/slack/adapter.py
@@ -8,10 +8,11 @@ import uuid
from collections import OrderedDict
from collections.abc import Awaitable, Callable
from dataclasses import replace
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Literal
import httpx
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+from pydantic.json_schema import SkipJsonSchema
from slack_sdk.errors import SlackApiError
from slack_sdk.socket_mode.aiohttp import SocketModeClient
from slack_sdk.socket_mode.request import SocketModeRequest
@@ -196,7 +197,29 @@ class SlackUser(BaseModel):
class SlackConnectionConfig(BridgeConnectionConfig):
bot_token: str
- app_token: str
+ #: How inbound events reach this bridge, which is decided by which Slack
+ #: app the token came from and is not an operator's preference.
+ #:
+ #: An app the operator registered themselves uses Socket Mode: Switch dials
+ #: out and needs no inbound route. The distributed app cannot — Slack does
+ #: not permit Socket Mode for it — so its events arrive as signed HTTP
+ #: posts to a public endpoint, and there is no app-level token at all.
+ #:
+ #: Hidden from the registration form because it is not a question an
+ #: operator filling that form can be asked: reaching the form at all means
+ #: Socket Mode, and the webhook value is written by the install flow.
+ event_delivery: SkipJsonSchema[Literal["socket_mode", "webhook"]] = "socket_mode"
+ #: Required under Socket Mode and meaningless without it, which the
+ #: validator below enforces rather than leaving to be discovered.
+ app_token: str | None = Field(
+ default=None,
+ title="App-level token",
+ description=(
+ "The xapp-… token with the connections:write scope, from the app's "
+ "Basic Information page. Required: it is what opens the connection "
+ "Slack delivers events down."
+ ),
+ )
workspace_id: str
# The descriptions are not decoration: both registration forms build
# themselves from this schema, so what is written here is the only
@@ -221,6 +244,28 @@ class SlackConnectionConfig(BridgeConnectionConfig):
),
)
+ @model_validator(mode="after")
+ def _app_token_matches_delivery(self) -> SlackConnectionConfig:
+ """Refuse the two states that would look configured and receive nothing.
+
+ A Socket Mode bridge with no app token opens no connection, so it
+ sends fine and never hears a word back — the exact shape of failure
+ that reads as "Slack is quiet today" for a week. An app token on a
+ webhook bridge is the opposite mistake: a credential for a mechanism
+ this bridge does not use, which will be read as evidence that it does.
+ """
+ if self.event_delivery == "socket_mode" and not self.app_token:
+ raise ValueError(
+ "app_token is required: without it Switch opens no Socket Mode "
+ "connection and this bridge would receive no Slack events at all."
+ )
+ if self.event_delivery == "webhook" and self.app_token:
+ raise ValueError(
+ "app_token must be empty for a bridge whose events arrive over "
+ "HTTP; the distributed Slack app has no app-level token."
+ )
+ return self
+
class SlackAdapter(CollaborationAdapter):
# Pin a turn's status to the message being worked on, opening a thread on
@@ -362,15 +407,28 @@ class SlackAdapter(CollaborationAdapter):
auth.get("team", ""),
)
- self._socket_client = SocketModeClient(
- app_token=self._config.app_token,
- web_client=self._web_client,
- )
- self._socket_client.socket_mode_request_listeners.append(
- self._handle_socket_event # type: ignore[arg-type]
- )
- await self._socket_client.connect()
- logger.info("Slack Socket Mode connected")
+ if self._config.event_delivery == "webhook":
+ # Nothing to connect: events are posted to the public endpoint,
+ # which verifies them and calls dispatch_event below. Said out loud
+ # because a bridge that opens no connection and logs nothing is
+ # indistinguishable from one that failed to.
+ logger.info(
+ "Slack adapter listening over HTTP; events arrive at the "
+ "messaging install endpoint rather than over Socket Mode"
+ )
+ else:
+ # Narrowing for the type checker; the config validator is what
+ # actually guarantees it.
+ assert self._config.app_token is not None
+ self._socket_client = SocketModeClient(
+ app_token=self._config.app_token,
+ web_client=self._web_client,
+ )
+ self._socket_client.socket_mode_request_listeners.append(
+ self._handle_socket_event # type: ignore[arg-type]
+ )
+ await self._socket_client.connect()
+ logger.info("Slack Socket Mode connected")
logger.debug(
_TRACE + "build carries agent sessions; config agent_sessions=%s",
self._config.agent_sessions,
@@ -1920,7 +1978,7 @@ class SlackAdapter(CollaborationAdapter):
return re.sub(r"@([A-Za-z0-9][A-Za-z0-9._-]*)", _replace, content)
- # ── Socket Mode event handling ───────────────────────────────────────────
+ # ── Event handling ───────────────────────────────────────────────────────
async def _handle_socket_event(
self, client: SocketModeClient, req: SocketModeRequest
@@ -1928,15 +1986,32 @@ class SlackAdapter(CollaborationAdapter):
await client.send_socket_mode_response(
SocketModeResponse(envelope_id=req.envelope_id)
)
+ await self.dispatch_event(envelope_type=req.type, payload=req.payload)
- if req.type == "slash_commands":
- await self._handle_slash_command(req.payload)
+ async def dispatch_event(
+ self, *, envelope_type: str, payload: dict[str, Any]
+ ) -> None:
+ """Route one Slack event, whichever transport carried it.
+
+ Socket Mode hands over an envelope type and a payload; the public
+ webhook parses the same two out of the request it has already proved
+ genuine. Everything after that point is identical, so it is written
+ once — a dispatch that differed by transport is how the two delivery
+ modes would drift into behaving differently for the same event.
+
+ Acknowledgement is *not* here, because the two transports acknowledge
+ incompatibly: Socket Mode replies on the socket before dispatching,
+ while HTTP acknowledges by returning 200 to the post. Both must do it
+ promptly and neither can do it for the other.
+ """
+ if envelope_type == "slash_commands":
+ await self._handle_slash_command(payload)
return
- if req.type != "events_api":
+ if envelope_type != "events_api":
return
- event = req.payload.get("event", {})
+ event = payload.get("event", {})
event_type = event.get("type")
event_subtype = event.get("subtype")
diff --git a/core/switch_core/bridges/collaboration/slack/install.py b/core/switch_core/bridges/collaboration/slack/install.py
new file mode 100644
index 000000000..cf63742ff
--- /dev/null
+++ b/core/switch_core/bridges/collaboration/slack/install.py
@@ -0,0 +1,153 @@
+"""Installing the distributed Slack app into a customer's workspace.
+
+The counterpart to `SLACK_SETUP.md`'s self-registered app, and a different
+Slack app from it. See `docs/old/bridges/SLACK_DISTRIBUTED_APP.md` for the
+registration walkthrough and the manifest; `BOT_SCOPES` below is the same list
+as that manifest's, and a test compares them so the two cannot drift.
+
+The one structural difference from the self-registered app runs through
+everything here: it has no app-level token, because Slack does not permit
+Socket Mode for a distributed app and a single socket could not be shared by
+replicas anyway. Events arrive over HTTPS and are proved genuine by the
+signing secret instead — which is why `verify_webhook` exists on this side of
+the boundary and has no equivalent on the adapter.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import ClassVar
+from urllib.parse import urlencode
+
+from slack_sdk.errors import SlackApiError
+from slack_sdk.signature import SignatureVerifier
+from slack_sdk.web.async_client import AsyncWebClient
+
+from switch_core.bridges.collaboration.install import (
+ InstallGrant,
+ MessagingAppInstaller,
+ MessagingInstallError,
+ WebhookAuthenticityError,
+)
+
+logger = logging.getLogger(__name__)
+
+AUTHORIZE_URL = "https://slack.com/oauth/v2/authorize"
+
+#: The bot scopes the distributed app requests, in the manifest's order.
+#:
+#: Identical to the self-registered app's: the two apps differ in how they are
+#: installed and how events reach them, never in what the bot may do once it is
+#: in a channel.
+BOT_SCOPES: tuple[str, ...] = (
+ "files:read",
+ "files:write",
+ "assistant:write",
+ "channels:history",
+ "channels:manage",
+ "channels:read",
+ "chat:write",
+ "chat:write.customize",
+ "commands",
+ "groups:history",
+ "groups:read",
+ "groups:write",
+ "im:history",
+ "im:read",
+ "im:write",
+ "mpim:history",
+ "reactions:read",
+ "reactions:write",
+ "users:read",
+ "usergroups:read",
+ "usergroups:write",
+)
+
+
+class SlackAppInstaller(MessagingAppInstaller):
+ platform: ClassVar[str] = "slack"
+
+ def __init__(
+ self, *, client_id: str, client_secret: str, signing_secret: str
+ ) -> None:
+ self._client_id = client_id
+ self._client_secret = client_secret
+ self._verifier = SignatureVerifier(signing_secret)
+
+ def authorize_url(self, *, state: str, redirect_uri: str) -> str:
+ return f"{AUTHORIZE_URL}?" + urlencode(
+ {
+ "client_id": self._client_id,
+ "scope": ",".join(BOT_SCOPES),
+ "redirect_uri": redirect_uri,
+ "state": state,
+ }
+ )
+
+ async def redeem(self, *, code: str, redirect_uri: str) -> InstallGrant:
+ try:
+ response = await AsyncWebClient().oauth_v2_access(
+ client_id=self._client_id,
+ client_secret=self._client_secret,
+ code=code,
+ redirect_uri=redirect_uri,
+ )
+ except SlackApiError as error:
+ raise MessagingInstallError(
+ f"Slack refused the install: {error.response.get('error', error)}"
+ ) from error
+
+ # Slack answers 200 with `ok: false` for most refusals, so the absence
+ # of an exception above proves nothing on its own.
+ if not response.get("ok"):
+ raise MessagingInstallError(
+ f"Slack refused the install: {response.get('error', 'unknown error')}"
+ )
+
+ if response.get("is_enterprise_install"):
+ raise MessagingInstallError(
+ "this app was installed org-wide on Slack Enterprise Grid, which "
+ "Switch cannot yet record: an org-wide install is identified by "
+ "an enterprise rather than by a single workspace, and an "
+ "installation is stored against one workspace. Install it into "
+ "a single workspace instead."
+ )
+
+ team = response.get("team") or {}
+ workspace_id = team.get("id")
+ access_token = response.get("access_token")
+ if not workspace_id or not access_token:
+ raise MessagingInstallError(
+ "Slack accepted the install but returned no workspace id or no "
+ "bot token, so there is nothing to record. Nothing was saved."
+ )
+
+ return InstallGrant(
+ external_workspace_id=workspace_id,
+ bot_token=access_token,
+ scopes=response.get("scope") or "",
+ )
+
+ def verify_webhook(self, *, headers: Mapping[str, str], body: bytes) -> None:
+ try:
+ valid = self._verifier.is_valid_request(body, dict(headers))
+ except ValueError as error:
+ # A non-numeric timestamp header reaches int() inside the verifier.
+ # It is unauthenticated input, so it must answer like any other bad
+ # signature rather than as a server fault.
+ raise WebhookAuthenticityError("malformed Slack timestamp") from error
+ if not valid:
+ raise WebhookAuthenticityError("bad Slack signature")
+
+ def workspace_of_event(self, payload: Mapping[str, object]) -> str:
+ workspace_id = payload.get("team_id")
+ if not isinstance(workspace_id, str) or not workspace_id:
+ raise WebhookAuthenticityError("Slack event names no workspace")
+ return workspace_id
+
+ def connection_config(self, grant: InstallGrant) -> dict[str, object]:
+ return {
+ "bot_token": grant.bot_token,
+ "workspace_id": grant.external_workspace_id,
+ }
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index ab01ca1f4..93683bbd9 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -178,6 +178,22 @@ class SwitchConfig(BaseSettings):
# unset, the raw `switchdash://` deeplink is posted as-is.
gateway_public_url: str | None = None
+ # Credentials of the distributed Slack app *we* registered — the one a
+ # customer installs by clicking a button, as opposed to the app an operator
+ # registers themselves and pastes tokens for. See
+ # `docs/old/bridges/SLACK_DISTRIBUTED_APP.md`.
+ #
+ # Setting all three is what enables workspace installs at all: there is no
+ # separate on/off switch, because an app with no credentials is not an app.
+ # Setting some is a mistake and is refused at startup.
+ #
+ # The signing secret is the one that must never be treated as optional in
+ # spirit: it is the whole of what distinguishes a Slack event from a post by
+ # anyone who learned the URL.
+ slack_app_client_id: str | None = None
+ slack_app_client_secret: str | None = None
+ slack_app_signing_secret: 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.
@@ -421,6 +437,34 @@ class SwitchConfig(BaseSettings):
)
return self
+ @model_validator(mode="after")
+ def _validate_slack_app(self) -> "SwitchConfig":
+ required = (
+ self.slack_app_client_id,
+ self.slack_app_client_secret,
+ self.slack_app_signing_secret,
+ )
+ set_count = sum(1 for value in required if value)
+ if 0 < set_count < len(required):
+ raise ValueError(
+ "Partial distributed Slack app config: set all of "
+ "SLACK_APP_CLIENT_ID / SLACK_APP_CLIENT_SECRET / "
+ "SLACK_APP_SIGNING_SECRET, or none of them."
+ )
+ # The redirect URI and the events URL are both built from the public
+ # origin, and Slack checks the redirect matches the one registered with
+ # 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:
+ raise ValueError(
+ "A distributed Slack app is configured but GATEWAY_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."
+ )
+ return self
+
@property
def gateway_oidc_enabled(self) -> bool:
return bool(
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 2ecd40132..ddc33ca2d 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -1205,6 +1205,59 @@ class MessagingInstall(TenantScoped, Base):
)
+class MessagingInstallState(TenantScoped, Base):
+ """One in-flight install: minted when the flow starts, burnt when it lands.
+
+ An install is two requests with a trip through the platform in between. The
+ first is an authenticated operator asking to install; the second is a
+ browser arriving back at a public endpoint from the platform, carrying an
+ authorization code and a `state` we chose. Nothing else ties the two
+ together, so `state` has to carry the whole of what the second request may
+ not be trusted to assert: which tenant, and on whose behalf.
+
+ **The row is not what carries the tenant across.** The `state` parameter is
+ a signed token naming the tenant, so the callback binds a tenant it can
+ verify without reading anything first. That is the point of the design:
+ every other unauthenticated entry point resolves its tenant through a
+ `SECURITY DEFINER` lookup, and this one does not have to, so it does not —
+ the closed list in `db/tenant_lookup.py` stays as short as it is. What this
+ row adds is the one property a signature cannot have: **single use.** A
+ signed token is valid until it expires and a captured one can be replayed;
+ the redemption below happens once because `consumed_at` is set in the same
+ statement that checks it is null.
+
+ Which makes the failure this prevents worth naming. Replaying a captured
+ state completes an install of the attacker's own workspace against the
+ victim's tenant — that workspace's messages then arrive in the victim's
+ rooms, which is message injection, not a leak. Single use and a short
+ expiry are what close it.
+
+ Redemption is a scoped write like any other, run after the signature has
+ bound the tenant, so row-level security is a second check on the first: a
+ token whose signed tenant disagrees with the row's finds no row at all.
+
+ The two timestamps are both needed and mean different things. `expires_at`
+ is a bound on how long the platform's round trip may take; `consumed_at`
+ is the fact of redemption, kept rather than deleted so an operator asking
+ why a link stopped working can see it was used rather than lost.
+ """
+
+ __tablename__ = "messaging_install_states"
+
+ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
+ platform: Mapped[str] = mapped_column(Text, nullable=False)
+ created_by_user_id: Mapped[str] = mapped_column(
+ Text, ForeignKey("users.id"), nullable=False
+ )
+ created_at: Mapped[str] = mapped_column(
+ DateTime(timezone=True), server_default=func.now(), nullable=False
+ )
+ expires_at: Mapped[str] = mapped_column(DateTime(timezone=True), nullable=False)
+ consumed_at: Mapped[str | None] = mapped_column(
+ DateTime(timezone=True), nullable=True
+ )
+
+
# ── Server-Side Connectors ────────────────────────────────────────────────────
diff --git a/core/switch_core/migrations/versions/d3f6b0c95a17_messaging_install_states.py b/core/switch_core/migrations/versions/d3f6b0c95a17_messaging_install_states.py
new file mode 100644
index 000000000..b5b8522cd
--- /dev/null
+++ b/core/switch_core/migrations/versions/d3f6b0c95a17_messaging_install_states.py
@@ -0,0 +1,87 @@
+"""messaging_install_states
+
+The other half of an install: the in-flight record that ties the operator who
+started one to the callback that finishes it. `messaging_installs` is the
+result; this is the ticket.
+
+It installs no lookup, and that is the interesting thing about it. The
+callback is as unauthenticated as the webhook is, so the obvious shape would
+have been a ninth `SECURITY DEFINER` function resolving a state to its tenant
+— exactly `tenant_of_api_key`'s shape, an opaque credential presented by a
+stranger. It is not needed: the `state` parameter is a token we signed, so the
+tenant travels inside it and the callback can bind before it reads. The row
+exists for the one thing a signature cannot do, which is to stop being valid
+the second time it is presented.
+
+So redemption is an ordinary scoped write — set `consumed_at` where it is
+still null, in one statement, and take the absence of a returned row as the
+refusal. Row-level security then checks the signature's claim a second time
+for free: a token naming the wrong tenant matches no row.
+
+The `tenant_isolation` policy is written out below rather than inherited,
+because `265ed188ad6f` installed the policies as they stood then and a table
+added afterwards has to bring its own. The DDL is a verbatim copy of
+`switch_core/db/rls_ddl.py` as it stood when this migration was written,
+copied rather than imported for the reason every revision in this chain
+copies: a migration records a change that already happened, and importing the
+live module would let a later edit silently change what this one means.
+`tests/switch_core/db/test_frozen_ddl_matches_create_all.py` is what keeps the
+copy from drifting.
+
+Revision ID: d3f6b0c95a17
+Revises: c8a4e21f6d30
+Create Date: 2026-09-11 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "d3f6b0c95a17"
+down_revision: str | None = "c8a4e21f6d30"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "messaging_install_states"
+POLICY_NAME = "tenant_isolation"
+
+ENABLE_RLS = f'ALTER TABLE "{TABLE}" ENABLE ROW LEVEL SECURITY'
+
+CREATE_POLICY = f"""CREATE POLICY {POLICY_NAME} ON "{TABLE}"
+ FOR ALL
+ USING ("tenant_id" = (SELECT require_tenant_id()))
+ WITH CHECK ("tenant_id" = (SELECT require_tenant_id()))"""
+
+DROP_POLICY = f'DROP POLICY IF EXISTS {POLICY_NAME} ON "{TABLE}"'
+
+
+def upgrade() -> None:
+ op.create_table(
+ TABLE,
+ sa.Column("id", sa.Text(), nullable=False),
+ sa.Column("tenant_id", sa.Text(), nullable=False),
+ sa.Column("platform", sa.Text(), nullable=False),
+ sa.Column("created_by_user_id", sa.Text(), nullable=False),
+ sa.Column(
+ "created_at",
+ sa.DateTime(timezone=True),
+ server_default=sa.text("now()"),
+ nullable=False,
+ ),
+ sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+ sa.Column("consumed_at", sa.DateTime(timezone=True), nullable=True),
+ sa.PrimaryKeyConstraint("id"),
+ sa.ForeignKeyConstraint(
+ ["tenant_id"], ["tenants.id"], name="fk_messaging_install_states_tenant"
+ ),
+ sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"]),
+ )
+ op.execute(ENABLE_RLS)
+ op.execute(CREATE_POLICY)
+
+
+def downgrade() -> None:
+ op.execute(DROP_POLICY)
+ op.drop_table(TABLE)
diff --git a/core/tests/switch_core/bridges/agent/test_version_is_not_public.py b/core/tests/switch_core/bridges/agent/test_version_is_not_public.py
index 8c946faa2..5d009dab3 100644
--- a/core/tests/switch_core/bridges/agent/test_version_is_not_public.py
+++ b/core/tests/switch_core/bridges/agent/test_version_is_not_public.py
@@ -39,4 +39,10 @@ def test_the_unauthenticated_allowlist_has_not_grown() -> None:
"/oauth",
"/gateway",
"/deeplink",
+ # Workspace installs of the distributed messaging apps: the OAuth
+ # callback and the platforms' event webhooks. Public because the
+ # callers are Slack and a browser mid-redirect, neither of which holds
+ # a credential of ours. Nothing under it discloses a version, and each
+ # route checks the platform's signature before it acts.
+ "/messaging",
}
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
index 34fafc77f..6d0bb7940 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py
@@ -100,7 +100,11 @@ def test_get_config_schema_exposes_required_fields() -> None:
"agent_usergroups",
"agent_sessions",
}
- assert set(schema["required"]) == {"bot_token", "app_token", "workspace_id"}
+ # app_token is offered but not required by the schema: a bridge whose
+ # events arrive over HTTP has none. What enforces it for a Socket Mode
+ # bridge — which receives nothing at all without one — is the model
+ # validator, not this form.
+ assert set(schema["required"]) == {"bot_token", "workspace_id"}
def test_get_config_schema_unknown_type_raises() -> None:
diff --git a/core/tests/switch_core/bridges/collaboration/test_slack_distributed_app.py b/core/tests/switch_core/bridges/collaboration/test_slack_distributed_app.py
new file mode 100644
index 000000000..1396c38ac
--- /dev/null
+++ b/core/tests/switch_core/bridges/collaboration/test_slack_distributed_app.py
@@ -0,0 +1,122 @@
+"""The registration walkthrough and the code have to agree, so this compares them.
+
+`docs/old/bridges/SLACK_DISTRIBUTED_APP.md` carries a manifest an operator
+pastes into Slack. Everything in it is a promise the running system has to
+keep: the scopes it requests are the scopes the authorize URL asks for, and
+the URLs it registers are the paths this application serves. Neither is
+checked by anything at runtime — Slack simply refuses a redirect that does not
+match, or grants a scope we never use, and the failure surfaces as a customer's
+install not working for a reason nobody can see from here.
+
+The manifest is parsed out of the markdown rather than kept in a fixture,
+because a fixture would be a third copy and the operator pastes the markdown.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+from switch_core.bridges.collaboration.install import (
+ commands_path,
+ events_path,
+ interactive_path,
+ oauth_callback_path,
+ public_url,
+)
+from switch_core.bridges.collaboration.slack.install import BOT_SCOPES
+
+_DOC = (
+ Path(__file__).resolve().parents[5]
+ / "docs"
+ / "old"
+ / "bridges"
+ / "SLACK_DISTRIBUTED_APP.md"
+)
+
+_HOST = "HOST"
+
+
[email protected](scope="module")
+def manifest() -> dict:
+ text = _DOC.read_text()
+ blocks = re.findall(r"```json\n(.*?)\n```", text, re.DOTALL)
+ assert len(blocks) == 1, (
+ f"expected exactly one json block in {_DOC.name}, found {len(blocks)}"
+ )
+ return json.loads(blocks[0])
+
+
+def test_the_manifest_requests_the_scopes_the_authorize_url_asks_for(
+ manifest: dict,
+) -> None:
+ """Same scopes, same order.
+
+ Order matters less to Slack than to a reader diffing the two, and keeping
+ it exact costs nothing.
+ """
+ assert tuple(manifest["oauth_config"]["scopes"]["bot"]) == BOT_SCOPES
+
+
+def test_the_manifest_registers_the_redirect_the_callback_is_served_at(
+ manifest: dict,
+) -> None:
+ """The one mismatch Slack refuses outright.
+
+ A redirect URI is compared byte for byte against the registered list, so a
+ path that drifted here is every install failing with `bad_redirect_uri`
+ and nothing in our logs at all — the refusal happens at Slack.
+ """
+ expected = public_url(f"https://{_HOST}", oauth_callback_path("slack"))
+ assert manifest["oauth_config"]["redirect_urls"] == [expected]
+
+
+def test_the_manifest_points_events_and_interactivity_at_the_served_paths(
+ manifest: dict,
+) -> None:
+ settings = manifest["settings"]
+ assert settings["event_subscriptions"]["request_url"] == public_url(
+ f"https://{_HOST}", events_path("slack")
+ )
+ assert settings["interactivity"]["request_url"] == public_url(
+ f"https://{_HOST}", interactive_path("slack")
+ )
+
+
+def test_every_slash_command_posts_to_the_commands_path(manifest: dict) -> None:
+ expected = public_url(f"https://{_HOST}", commands_path("slack"))
+ urls = {command["url"] for command in manifest["features"]["slash_commands"]}
+ assert urls == {expected}
+
+
+def test_the_manifest_does_not_enable_socket_mode(manifest: dict) -> None:
+ """The property the whole distributed app exists to have.
+
+ Slack forbids Socket Mode for a Marketplace-listed app, and a single
+ socket could not be shared across replicas even if it did not. Turning it
+ on here would produce an app that works in a one-replica test and silently
+ delivers to one arbitrary replica in production.
+ """
+ assert manifest["settings"]["socket_mode_enabled"] is False
+
+
+def test_the_manifest_does_not_declare_the_app_an_agent(manifest: dict) -> None:
+ """`agent_view` is irreversible per app and needs re-review to distribute.
+
+ Left out deliberately rather than forgotten — see the doc. If it is added,
+ that is a decision, and this test is where it gets recorded as one.
+ """
+ assert "agent_view" not in manifest["features"]
+
+
+def test_the_manifest_does_not_enable_org_wide_deploy(manifest: dict) -> None:
+ """An org-wide install has an enterprise id and no single workspace id.
+
+ `messaging_installs` is unique on `(platform, external_workspace_id)` and
+ the installer refuses an enterprise install outright, so enabling this
+ would offer customers a button that always fails.
+ """
+ assert manifest["settings"]["org_deploy_enabled"] is False
diff --git a/core/tests/switch_core/bridges/collaboration/test_slack_installer.py b/core/tests/switch_core/bridges/collaboration/test_slack_installer.py
new file mode 100644
index 000000000..aa7e6499a
--- /dev/null
+++ b/core/tests/switch_core/bridges/collaboration/test_slack_installer.py
@@ -0,0 +1,299 @@
+"""What the installer does with what Slack sends back, including when it lies.
+
+The install endpoints are the only ones in the system a stranger can reach
+with no credential at all, so the interesting cases here are the hostile and
+the malformed ones rather than the happy path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+import pytest
+from slack_sdk.web.async_client import AsyncWebClient
+
+from switch_core.bridges.collaboration.install import (
+ InstallGrant,
+ MessagingInstallerRegistry,
+ MessagingInstallError,
+ WebhookAuthenticityError,
+ events_path,
+ oauth_callback_path,
+ public_url,
+)
+from switch_core.bridges.collaboration.slack.adapter import SlackConnectionConfig
+from switch_core.bridges.collaboration.slack.install import (
+ BOT_SCOPES,
+ SlackAppInstaller,
+)
+
+_SIGNING_SECRET = "test-signing-secret"
+
+
+def installer() -> SlackAppInstaller:
+ return SlackAppInstaller(
+ client_id="1234.5678",
+ client_secret="test-client-secret",
+ signing_secret=_SIGNING_SECRET,
+ )
+
+
+def _sign(body: bytes, timestamp: str) -> str:
+ digest = hmac.new(
+ _SIGNING_SECRET.encode(),
+ b"v0:" + timestamp.encode() + b":" + body,
+ hashlib.sha256,
+ ).hexdigest()
+ return f"v0={digest}"
+
+
+def _signed_headers(body: bytes, *, age_seconds: int = 0) -> dict[str, str]:
+ timestamp = str(int(time.time()) - age_seconds)
+ return {
+ "X-Slack-Request-Timestamp": timestamp,
+ "X-Slack-Signature": _sign(body, timestamp),
+ }
+
+
+class TestAuthorizeUrl:
+ def test_it_carries_the_state_and_redirect_unchanged(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ redirect = public_url("https://switch.example", oauth_callback_path("slack"))
+ url = installer.authorize_url(state="opaque-state", redirect_uri=redirect)
+
+ assert url.startswith("https://slack.com/oauth/v2/authorize?")
+ assert "state=opaque-state" in url
+ assert (
+ "redirect_uri=https%3A%2F%2Fswitch.example%2Fmessaging%2Fslack%2Foauth%2Fcallback"
+ in url
+ )
+
+ def test_it_asks_for_every_scope_the_bot_needs(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ url = installer.authorize_url(state="s", redirect_uri="https://x.example/cb")
+ for scope in BOT_SCOPES:
+ assert scope.replace(":", "%3A") in url
+
+
+class TestWebhookVerification:
+ def test_a_correctly_signed_body_passes(self, installer: SlackAppInstaller) -> None:
+ body = b'{"type":"event_callback","team_id":"T1"}'
+ installer.verify_webhook(headers=_signed_headers(body), body=body)
+
+ def test_a_tampered_body_is_refused(self, installer: SlackAppInstaller) -> None:
+ body = b'{"type":"event_callback","team_id":"T1"}'
+ headers = _signed_headers(body)
+ with pytest.raises(WebhookAuthenticityError):
+ installer.verify_webhook(headers=headers, body=body + b" ")
+
+ def test_an_old_signature_is_refused(self, installer: SlackAppInstaller) -> None:
+ """Replay window. A capture stays valid forever without it."""
+ body = b'{"team_id":"T1"}'
+ with pytest.raises(WebhookAuthenticityError):
+ installer.verify_webhook(
+ headers=_signed_headers(body, age_seconds=60 * 10), body=body
+ )
+
+ def test_missing_headers_are_refused_rather_than_skipped(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ with pytest.raises(WebhookAuthenticityError):
+ installer.verify_webhook(headers={}, body=b"{}")
+
+ def test_a_nonnumeric_timestamp_is_a_bad_signature_not_a_crash(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ """Reachable by anyone who finds the URL.
+
+ The verifier calls `int()` on the header, so without the guard this
+ unauthenticated input is a 500 and a traceback per request rather than
+ a 401.
+ """
+ body = b"{}"
+ with pytest.raises(WebhookAuthenticityError):
+ installer.verify_webhook(
+ headers={
+ "X-Slack-Request-Timestamp": "not-a-number",
+ "X-Slack-Signature": "v0=deadbeef",
+ },
+ body=body,
+ )
+
+ def test_header_case_does_not_matter(self, installer: SlackAppInstaller) -> None:
+ body = b'{"team_id":"T1"}'
+ headers = {k.lower(): v for k, v in _signed_headers(body).items()}
+ installer.verify_webhook(headers=headers, body=body)
+
+
+class TestWorkspaceOfEvent:
+ def test_it_reads_the_team_id(self, installer: SlackAppInstaller) -> None:
+ assert installer.workspace_of_event({"team_id": "T123"}) == "T123"
+
+ @pytest.mark.parametrize("payload", [{}, {"team_id": ""}, {"team_id": 7}])
+ def test_an_event_naming_no_workspace_is_refused(
+ self, installer: SlackAppInstaller, payload: dict
+ ) -> None:
+ """An event we cannot route is not an event to guess at.
+
+ There is no sensible default here: picking any tenant would deliver a
+ stranger's message into somebody's rooms.
+ """
+ with pytest.raises(WebhookAuthenticityError):
+ installer.workspace_of_event(payload)
+
+
+class TestRedeem:
+ async def _redeem_returning(
+ self, monkeypatch: pytest.MonkeyPatch, installer: SlackAppInstaller, response
+ ) -> InstallGrant:
+ async def fake(self, **kwargs): # noqa: ANN001, ANN202
+ return response
+
+ monkeypatch.setattr(AsyncWebClient, "oauth_v2_access", fake)
+ return await installer.redeem(code="c", redirect_uri="https://x.example/cb")
+
+ async def test_a_good_grant_becomes_the_three_things_we_keep(
+ self, installer: SlackAppInstaller, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ grant = await self._redeem_returning(
+ monkeypatch,
+ installer,
+ {
+ "ok": True,
+ "access_token": "xoxb-granted",
+ "scope": "chat:write,commands",
+ "team": {"id": "T123", "name": "Acme"},
+ },
+ )
+ assert grant == InstallGrant(
+ external_workspace_id="T123",
+ bot_token="xoxb-granted",
+ scopes="chat:write,commands",
+ )
+
+ async def test_a_two_hundred_saying_not_ok_is_still_a_failure(
+ self, installer: SlackAppInstaller, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Slack answers 200 with `ok: false` for most refusals."""
+ with pytest.raises(MessagingInstallError, match="invalid_code"):
+ await self._redeem_returning(
+ monkeypatch, installer, {"ok": False, "error": "invalid_code"}
+ )
+
+ async def test_an_org_wide_install_is_refused_with_a_reason(
+ self, installer: SlackAppInstaller, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """It has an enterprise id and no single workspace id to be unique on."""
+ with pytest.raises(MessagingInstallError, match="org-wide"):
+ await self._redeem_returning(
+ monkeypatch,
+ installer,
+ {
+ "ok": True,
+ "access_token": "xoxb-granted",
+ "is_enterprise_install": True,
+ "enterprise": {"id": "E1"},
+ "team": None,
+ },
+ )
+
+ async def test_a_grant_with_no_workspace_is_refused(
+ self, installer: SlackAppInstaller, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ with pytest.raises(MessagingInstallError, match="nothing to record"):
+ await self._redeem_returning(
+ monkeypatch, installer, {"ok": True, "access_token": "xoxb-granted"}
+ )
+
+
+class TestConnectionConfig:
+ def test_a_grant_renders_a_config_the_adapter_accepts(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ """The seam: after this an installed bridge is an ordinary bridge."""
+ rendered = installer.connection_config(
+ InstallGrant(
+ external_workspace_id="T123",
+ bot_token="xoxb-granted",
+ scopes="chat:write",
+ )
+ )
+ config = SlackConnectionConfig.model_validate(
+ {**rendered, "event_delivery": "webhook"}
+ )
+ assert config.bot_token == "xoxb-granted"
+ assert config.workspace_id == "T123"
+ assert config.app_token is None
+
+
+class TestDeliveryModeValidation:
+ def test_socket_mode_without_an_app_token_is_refused(self) -> None:
+ """The failure that otherwise reads as "Slack is quiet today"."""
+ with pytest.raises(ValueError, match="app_token is required"):
+ SlackConnectionConfig.model_validate(
+ {"bot_token": "xoxb-x", "workspace_id": "T1"}
+ )
+
+ def test_a_webhook_bridge_with_an_app_token_is_refused(self) -> None:
+ with pytest.raises(ValueError, match="must be empty"):
+ SlackConnectionConfig.model_validate(
+ {
+ "bot_token": "xoxb-x",
+ "workspace_id": "T1",
+ "app_token": "xapp-x",
+ "event_delivery": "webhook",
+ }
+ )
+
+ def test_the_hand_registered_shape_still_validates(self) -> None:
+ config = SlackConnectionConfig.model_validate(
+ {"bot_token": "xoxb-x", "app_token": "xapp-x", "workspace_id": "T1"}
+ )
+ assert config.event_delivery == "socket_mode"
+
+ def test_the_registration_form_never_offers_the_delivery_mode(self) -> None:
+ """It is not a question an operator filling that form can be asked."""
+ assert (
+ "event_delivery"
+ not in SlackConnectionConfig.model_json_schema()["properties"]
+ )
+
+
+class TestRegistry:
+ def test_an_unregistered_platform_says_what_to_do(self) -> None:
+ registry = MessagingInstallerRegistry()
+ with pytest.raises(MessagingInstallError, match="no slack app is registered"):
+ registry.get("slack")
+
+ def test_registering_twice_is_refused(self, installer: SlackAppInstaller) -> None:
+ registry = MessagingInstallerRegistry()
+ registry.register(installer)
+ with pytest.raises(MessagingInstallError, match="already registered"):
+ registry.register(installer)
+
+ def test_a_registered_installer_comes_back(
+ self, installer: SlackAppInstaller
+ ) -> None:
+ registry = MessagingInstallerRegistry()
+ registry.register(installer)
+ assert registry.get("slack") is installer
+ assert registry.platforms() == ["slack"]
+
+
+class TestPaths:
+ def test_the_public_prefix_bypasses_bearer_auth(self) -> None:
+ """Otherwise every Slack event is a 401 nobody sees."""
+ from switch_core.bridges.agent.auth import PUBLIC_PATH_PREFIXES
+
+ assert events_path("slack").startswith(PUBLIC_PATH_PREFIXES)
+
+ def test_joining_an_origin_with_a_trailing_slash_does_not_double_it(self) -> None:
+ """Slack compares the redirect byte for byte."""
+ assert public_url(
+ "https://switch.example/", oauth_callback_path("slack")
+ ) == public_url("https://switch.example", oauth_callback_path("slack"))
diff --git a/core/tests/switch_core/db/test_row_level_security.py b/core/tests/switch_core/db/test_row_level_security.py
index c6a1a6ca8..0a3945552 100644
--- a/core/tests/switch_core/db/test_row_level_security.py
+++ b/core/tests/switch_core/db/test_row_level_security.py
@@ -46,8 +46,6 @@ from switch_core.db.rls_ddl import (
GLOBAL_TABLES,
POLICY_NAME,
REQUIRE_TENANT_FUNCTION_NAME,
- create_policy_ddl,
- enable_rls_ddl,
scoped_tables,
unscoped_tables,
)
diff --git a/core/tests/switch_core/test_config_slack_app.py b/core/tests/switch_core/test_config_slack_app.py
new file mode 100644
index 000000000..5c9c18222
--- /dev/null
+++ b/core/tests/switch_core/test_config_slack_app.py
@@ -0,0 +1,63 @@
+"""Half-configuring the distributed Slack app has to be a startup error.
+
+Each of the three credentials fails differently and none of them fails
+usefully. Without the client id and secret the code exchange is refused by
+Slack; without the signing secret there is nothing distinguishing a real event
+from a post by anyone who found the URL. A deployment that sets two of three
+looks configured, offers the button, and breaks at the worst moment — so it
+does not start.
+"""
+
+import pytest
+
+from switch_core.config import SwitchConfig
+
+_BASE_KWARGS = dict(
+ db_host="db",
+ db_port="5432",
+ db_user="postgres",
+ db_password="pw",
+ db_name="switch",
+ matrix_server_name="switch.local",
+ agent_registration_token="token",
+ jwt_secret_key="jwt",
+ gateway_admin_email="[email protected]",
+ gateway_admin_password="pw",
+)
+
+_APP = dict(
+ slack_app_client_id="1234.5678",
+ slack_app_client_secret="secret",
+ slack_app_signing_secret="signing",
+)
+
+
+def _config(**overrides: object) -> SwitchConfig:
+ return SwitchConfig(**{**_BASE_KWARGS, **overrides}) # type: ignore[arg-type]
+
+
+def test_setting_none_of_them_is_the_ordinary_case() -> None:
+ assert _config().slack_app_client_id is None
+
+
+def test_setting_all_three_with_a_public_origin_is_accepted() -> None:
+ config = _config(**_APP, gateway_public_url="https://switch.example")
+ assert config.slack_app_signing_secret == "signing"
+
+
[email protected]("missing", sorted(_APP))
+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")
+
+
+def test_an_app_with_no_public_origin_raises() -> None:
+ """The redirect and the events URL are both built from it.
+
+ Slack compares the redirect against the one registered with the app, so
+ building it against nothing is an install that fails at Slack with nothing
+ in our logs.
+ """
+ with pytest.raises(ValueError, match="GATEWAY_PUBLIC_URL"):
+ _config(**_APP)
diff --git a/docs/old/bridges/README.md b/docs/old/bridges/README.md
index fffa6b0bf..38a105e37 100644
--- a/docs/old/bridges/README.md
+++ b/docs/old/bridges/README.md
@@ -19,6 +19,12 @@ shared onboarding model, then the per-platform guide:
| Discord | [`DISCORD_SETUP.md`](DISCORD_SETUP.md) | single bot app | Gateway WebSocket (outbound) | not required |
| Telegram | [`TELEGRAM_SETUP.md`](TELEGRAM_SETUP.md) | single bot, agent named in the message body | long polling (outbound) | not required |
+Every guide above describes an app the operator registers themselves and
+supplies the credentials for. Slack additionally has a **distributed** app —
+one we register and a customer installs by clicking a button, receiving events
+over HTTPS rather than Socket Mode. It is a separate Slack app with different
+requirements: see [`SLACK_DISTRIBUTED_APP.md`](SLACK_DISTRIBUTED_APP.md).
+
## The onboarding model (same for every bridge)
A bridge is an **unowned, workspace-wide integration** that holds platform
diff --git a/docs/old/bridges/SLACK_DISTRIBUTED_APP.md b/docs/old/bridges/SLACK_DISTRIBUTED_APP.md
new file mode 100644
index 000000000..3294bde14
--- /dev/null
+++ b/docs/old/bridges/SLACK_DISTRIBUTED_APP.md
@@ -0,0 +1,202 @@
+# The distributed Slack app
+
+`SLACK_SETUP.md` describes the app **an operator registers for themselves**:
+they create it, install it into their own workspace, and paste its tokens into
+Switch. This page describes the other one — the app **we** register and
+distribute, which a customer installs by clicking a button and which never
+requires them to see a token at all.
+
+They are two separate Slack apps and they will both exist. Nothing here
+replaces the other page.
+
+## Why it cannot be the same app
+
+The self-registered app uses **Socket Mode**: Switch dials out to Slack and
+events arrive down that connection, so the deployment needs no inbound route
+from the internet. That is the right shape for a self-hosted operator and the
+wrong shape here, for two independent reasons:
+
+- Slack does not permit Socket Mode for apps listed on the Marketplace.
+- A Socket Mode connection is opened with one app-level token by one process.
+ Every installing workspace's events would arrive down that single socket, so
+ the moment Switch runs more than one replica the events land on whichever
+ replica happens to hold the connection.
+
+So the distributed app receives events over HTTPS instead, at a public URL.
+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.
+
+| Slack setting | Path |
+| --- | --- |
+| **OAuth & Permissions → Redirect URLs** | `/messaging/slack/oauth/callback` |
+| **Event Subscriptions → Request URL** | `/messaging/slack/events` |
+| **Interactivity & Shortcuts → Request URL** | `/messaging/slack/interactive` |
+| **Slash Commands → each command's URL** | `/messaging/slack/commands` |
+
+`/messaging` is a public prefix in its own right: it is unauthenticated by
+nature, because a Slack event arrives with no credential of ours and an OAuth
+callback arrives before there is anything to authenticate against. It is
+deliberately not `/gateway` — that prefix is cookie-authenticated and is not
+routed to this application from the outside — and deliberately not `/oauth`,
+which already belongs to agents authenticating *to* Switch and would collide
+in name only, confusingly.
+
+Reaching it from the internet needs the prefix added in two places: the
+application's own public-path list, and the deployment's ingress path
+allowlist.
+
+## Registering the app
+
+**Slack verifies the Request URL the moment you save it**, by posting a
+challenge it expects the endpoint to echo back. So the order matters: you can
+create the app and collect its credentials before the endpoints exist, but you
+cannot fill in the URL fields until they are live and publicly reachable.
+
+1. <https://api.slack.com/apps> → **Create New App** → **From an app
+ manifest**, in a workspace we control. Paste the manifest below, with the
+ host substituted.
+2. **Basic Information → App Credentials.** Take the **Client ID**, **Client
+ Secret** and **Signing Secret**. The signing secret is what proves an
+ inbound webhook came from Slack; the client id and secret are what exchange
+ an install code for a bot token. There is no app-level token and no bot
+ token here — a bot token belongs to an installation, not to the app, and
+ arrives one per customer.
+3. **Manage Distribution → Activate Public Distribution.** This is what makes
+ the app installable outside our own workspace and produces the *Add to
+ Slack* URL. Slack requires every hardcoded workspace reference to be removed
+ first.
+4. Marketplace listing is a separate, reviewed submission, and is not required
+ for a customer to install by link.
+
+## Manifest
+
+Substitute the host in the four `url` fields. The scopes, slash commands and
+bot events are identical to the self-registered app's, because the app does
+the same job once installed — the differences are all in `settings` and
+`oauth_config`.
+
+```json
+{
+ "display_information": {
+ "name": "Agent Switch"
+ },
+ "features": {
+ "app_home": {
+ "home_tab_enabled": true,
+ "messages_tab_enabled": false,
+ "messages_tab_read_only_enabled": false
+ },
+ "bot_user": {
+ "display_name": "Agent Switch",
+ "always_online": false
+ },
+ "slash_commands": [
+ { "command": "/admin", "url": "https://HOST/messaging/slack/commands", "description": "Toggle admin mode on/off for this room", "should_escape": false },
+ { "command": "/help", "url": "https://HOST/messaging/slack/commands", "description": "Show the list of available in-room commands", "should_escape": false },
+ { "command": "/reset", "url": "https://HOST/messaging/slack/commands", "description": "Reset a targeted agent's session (clears context, then reconnects)", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/reset-all-agents", "url": "https://HOST/messaging/slack/commands", "description": "Reset EVERY agent's session in this room", "should_escape": false },
+ { "command": "/compact", "url": "https://HOST/messaging/slack/commands", "description": "Compact a targeted agent's session context", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/compact-all-agents", "url": "https://HOST/messaging/slack/commands", "description": "Compact EVERY agent's session context in this room", "should_escape": false },
+ { "command": "/interrupt", "url": "https://HOST/messaging/slack/commands", "description": "Interrupt a targeted agent's current turn", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/interrupt-all-agents", "url": "https://HOST/messaging/slack/commands", "description": "Interrupt EVERY agent's current turn in this room", "should_escape": false },
+ { "command": "/agents-status", "url": "https://HOST/messaging/slack/commands", "description": "Show each agent's presence and capabilities in this room", "should_escape": false },
+ { "command": "/roles", "url": "https://HOST/messaging/slack/commands", "description": "List this room's roles and who currently holds each", "should_escape": false },
+ { "command": "/list-agents", "url": "https://HOST/messaging/slack/commands", "description": "List the agents available in this room", "should_escape": false },
+ { "command": "/list-switch-agents", "url": "https://HOST/messaging/slack/commands", "description": "List all agents registered on the Switch", "should_escape": false },
+ { "command": "/list-documents", "url": "https://HOST/messaging/slack/commands", "description": "List the room's internal documents", "should_escape": false },
+ { "command": "/list-references", "url": "https://HOST/messaging/slack/commands", "description": "List the room's references", "should_escape": false },
+ { "command": "/list-aliases", "url": "https://HOST/messaging/slack/commands", "description": "List per-room agent aliases (@alias to agent)", "should_escape": false },
+ { "command": "/set-alias", "url": "https://HOST/messaging/slack/commands", "description": "Give an agent a room alias", "usage_hint": "@agent-name @alias", "should_escape": true },
+ { "command": "/remove-alias", "url": "https://HOST/messaging/slack/commands", "description": "Remove a room alias", "usage_hint": "@alias (or @agent-name)", "should_escape": true },
+ { "command": "/invite-agent", "url": "https://HOST/messaging/slack/commands", "description": "Add an existing agent to this room", "usage_hint": "@agent-name", "should_escape": true },
+ { "command": "/run-cmd", "url": "https://HOST/messaging/slack/commands", "description": "Show the terminal command to start a session for an agent", "usage_hint": "@agent-name [@role]", "should_escape": true },
+ { "command": "/agents-greet", "url": "https://HOST/messaging/slack/commands", "description": "Have agents in the room introduce themselves", "should_escape": false },
+ { "command": "/room-url", "url": "https://HOST/messaging/slack/commands", "description": "Show the frontend URL for this room", "should_escape": false }
+ ]
+ },
+ "oauth_config": {
+ "redirect_urls": [
+ "https://HOST/messaging/slack/oauth/callback"
+ ],
+ "scopes": {
+ "bot": [
+ "files:read",
+ "files:write",
+ "assistant:write",
+ "channels:history",
+ "channels:manage",
+ "channels:read",
+ "chat:write",
+ "chat:write.customize",
+ "commands",
+ "groups:history",
+ "groups:read",
+ "groups:write",
+ "im:history",
+ "im:read",
+ "im:write",
+ "mpim:history",
+ "reactions:read",
+ "reactions:write",
+ "users:read",
+ "usergroups:read",
+ "usergroups:write"
+ ]
+ },
+ "pkce_enabled": false
+ },
+ "settings": {
+ "event_subscriptions": {
+ "request_url": "https://HOST/messaging/slack/events",
+ "bot_events": [
+ "message.channels",
+ "message.groups",
+ "message.im",
+ "message.mpim"
+ ]
+ },
+ "interactivity": {
+ "is_enabled": true,
+ "request_url": "https://HOST/messaging/slack/interactive"
+ },
+ "org_deploy_enabled": false,
+ "socket_mode_enabled": false,
+ "token_rotation_enabled": false,
+ "is_mcp_enabled": false
+ }
+}
+```
+
+## Three things left out on purpose
+
+**`agent_view`.** The self-registered app declares itself a Slack agent, which
+is what turns DMs into threads and puts progress on the message. Declaring it
+is irreversible per app, removes guest access from the workspace, and requires
+re-review for a distributed app. It should be a deliberate later step with
+that review budgeted, not something a customer discovers after installing.
+
+**`org_deploy_enabled`.** An Enterprise Grid org-wide install identifies itself
+by enterprise id rather than by a single workspace id. `messaging_installs` is
+unique on `(platform, external_workspace_id)` and an org install does not have
+one of those, so enabling this is a schema question and not a checkbox.
+
+**`token_rotation_enabled`.** Rotating tokens means storing a refresh token,
+refreshing before expiry, and handling a refresh that fails while events are
+arriving. Worth doing, and not worth doing at the same time as everything
+else; a non-rotating bot token is what the self-registered app already uses.
+
+## What a customer's install produces
+
+One row in `messaging_installs`: the workspace it was installed into, the bot
+token that install granted (encrypted), the scopes Slack actually approved,
+and the tenant and user who initiated it. `(platform, external_workspace_id)`
+is unique across the whole deployment, because an inbound event carries a
+workspace id and no tenant — a workspace claimed by two tenants would be an
+event with two possible destinations. A second tenant attempting to claim an
+already-claimed workspace is refused by the database.
diff --git a/docs/old/bridges/SLACK_SETUP.md b/docs/old/bridges/SLACK_SETUP.md
index da8182690..4f69fefc2 100644
--- a/docs/old/bridges/SLACK_SETUP.md
+++ b/docs/old/bridges/SLACK_SETUP.md
@@ -6,6 +6,11 @@ avatar overrides. Inbound events arrive over **Socket Mode** — an outbound
WebSocket the bot opens to Slack — so **no public ingress is required**. Outbound
messages go through the Slack Web API.
+This page is about the app **you** register and hold the tokens for. There is
+also a distributed app that we register and you install by clicking a button;
+it is a different Slack app with different requirements, described in
+[`SLACK_DISTRIBUTED_APP.md`](SLACK_DISTRIBUTED_APP.md).
+
## Prerequisites
- A Slack workspace where you can install a custom app (workspace admin approval