sandbox-quantum · lbangalosbt · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
@@ -121,6 +121,35 @@ 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=
+
+# Credentials of the distributed Discord app — the one a customer adds to their
+# server by clicking "Add to Server", not the self-registered app whose token an
+# operator pastes in (DISCORD_SETUP.md). Set all four or none; setting some is
+# refused at startup, and MESSAGING_PUBLIC_URL must be set with them. The bot
+# token lives here, in deployment config, because a Discord install carries no
+# per-install token. See docs/old/bridges/DISCORD_DISTRIBUTED_APP.md.
+# DISCORD_APP_CLIENT_ID=
+# DISCORD_APP_CLIENT_SECRET=
+# DISCORD_APP_BOT_TOKEN=
+# DISCORD_APP_APPLICATION_ID=
+# Privileged intents on the shared connection, each off by default (mention-only
+# / API member fetches) and requiring Discord verification past ~100 guilds.
+# DISCORD_APP_MESSAGE_CONTENT=false
+# DISCORD_APP_MEMBERS=false
+
 # ── Mattermost (local dev) ───────────────────────────────────────────────────
 MATTERMOST_ADMIN_USER=admin
 MATTERMOST_ADMIN_PASSWORD=

@@ -44,6 +44,10 @@ regexes = [
   # Collaboration-adapter type registration; the mattermost-access-token
   # rule mistakes the identifier sequence for a token. No secret here.
   '''"mattermost", MattermostAdapter, MattermostConnectionConfig''',
+  # A Discord client/application id is a *public* identifier, not a secret, and
+  # these are obvious dummies in a config-validator test — but the default
+  # `discord-client-id` rule flags any 17-19 digit number next to the keyword.
+  '''discord_app_(?:client|application)_id="\d{17,19}"''',
 ]
 paths = [
   # Log-redaction tests exercise deliberately fake vendor tokens. Both spellings

@@ -90,9 +90,24 @@ describe('buildEnvFile', () => {
     const interpolated = new Set(
       [...composeBody.matchAll(/\$\{([A-Z_][A-Z0-9_]*)/g)].map((m) => m[1])
     );
-    // Nothing is exempt today. An entry here must say why the stack is correct
-    // without it — leaving a var unset is a decision, not a default.
-    const intentionallyUnset = new Set<string>();
+    // An entry here must say why the stack is correct without it — leaving a
+    // var unset is a decision, not a default.
+    const intentionallyUnset = new Set<string>([
+      // The four below configure switch-core as a distributed messaging app —
+      // one app we own, installed by a customer into their own workspace, with
+      // the platform posting events to URLs declared once in the app manifest.
+      // A managed stack cannot be one of those and is not meant to be: it binds
+      // to loopback, so no platform can reach its callback or event URLs, and
+      // the credentials are the app owner's rather than anything this machine
+      // could hold. switch-core registers no installer without them and the
+      // operator UI says so rather than offering a button that would fail at
+      // Slack. Connecting a workspace from here is the other path — an operator
+      // registering a bridge with their own app's token.
+      'MESSAGING_PUBLIC_URL',
+      'SLACK_APP_CLIENT_ID',
+      'SLACK_APP_CLIENT_SECRET',
+      'SLACK_APP_SIGNING_SECRET',
+    ]);
 
     const missing = [...interpolated]
       .filter((key) => !intentionallyUnset.has(key))

@@ -214,6 +214,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

@@ -12,6 +12,9 @@
 
 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 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,
 )
 
 

@@ -5,7 +5,7 @@
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, replace
-from typing import ClassVar
+from typing import Any, ClassVar
 
 from switch_core.agent_display_name import defuse_label_markup
 from switch_core.agent_icon import default_icon_url
@@ -20,6 +20,7 @@
     InboundMessage,
     InboundUserJoin,
     OutboundAttachment,
+    WebhookDeliveryUnsupported,
 )
 
 logger = logging.getLogger(__name__)
@@ -248,6 +249,29 @@ async def start(
     @abstractmethod
     async def stop(self) -> None: ...
 
+    async def dispatch_event(
+        self, *, envelope_type: str, payload: dict[str, Any]
+    ) -> None:
+        """Handle one event that arrived over the public webhook.
+
+        Concrete on the base and raising, rather than abstract, because
+        receiving events over HTTP is a property of a platform and of which app
+        a bridge's token came from — most adapters dial out and are handed
+        their events on a connection they opened, and have nothing to override
+        here.
+
+        Raising rather than returning quietly matters: the caller is a route
+        that has already proved the request genuine and resolved which bridge
+        it belongs to, so reaching an adapter that cannot take it means a
+        workspace's traffic is being delivered nowhere. Silence there is the
+        failure that reads as "the platform has gone quiet".
+        """
+        raise WebhookDeliveryUnsupported(
+            f"{type(self).__name__} does not receive events over HTTP, so the "
+            "event posted for this bridge cannot be delivered. A bridge reached "
+            "this way was installed as a distributed app; this one was not."
+        )
+
     @abstractmethod
     async def send_message(
         self,