fix(slack): scope channel action tokens

Author: osolmaz

docs/2026-04-26-channel-delivery-feedback-architecture.md

@@ -199,6 +199,9 @@ Slack requirements:
 - existing Slack installs must be reauthorized before reaction feedback works
 - the provider action/tool surface must expose reaction add/remove operations
   when users should be able to ask the agent to react to messages
+- provider-action tokens must be scoped to the channel or installation they are
+  allowed to mutate; a shared gateway token must not authorize arbitrary
+  caller-supplied Slack channel ids
 - reaction failures such as missing scope, already-reacted, or no-reaction must
   be logged but must not block runtime delivery
 - gateway retries must be idempotent
@@ -242,6 +245,12 @@ endpoint, and the gateway performs the Slack API call with its stored provider
 auth. The runtime receives tool success or failure, but it never receives the
 Slack bot token.
 
+The gateway must validate both the action token and the requested target. A
+valid token should carry authority only for specific Slack team/channel targets,
+or for a specific installation whose channel set is resolved by the gateway.
+That prevents a runtime attached to one channel from asking the gateway to react
+inside another installed channel just because it knows the Slack ids.
+
 The important boundary is:
 
 - automatic delivery feedback is gateway-owned
@@ -343,6 +352,19 @@ the box without adding deployment-specific values:
 }
 ```
 
+Deployments that enable the channel-action MCP server must give the gateway a
+matching scoped token binding. The portable single-token form is:
+
+```env
+SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN=change-me
+SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS=T_example:C_example
+```
+
+For multiple independent runtimes or owners, deployments should mint distinct
+tokens and bind each token only to the team/channel targets that runtime may
+mutate. A gateway may also accept structured token bindings, but the same rule
+holds: authorization is token plus target, not token alone.
+
 These defaults are safe for Spritz because they are:
 
 - provider-neutral OpenClaw settings

images/examples/openclaw/README.md

@@ -118,7 +118,9 @@ configuration.
 The channel-action MCP server expects `SPRITZ_CHANNEL_ACTIONS_BASE_URL` and
 `SPRITZ_CHANNEL_ACTIONS_TOKEN` when provider actions should be enabled. It calls
 the Spritz channel gateway action API, so provider tokens remain outside the
-runtime.
+runtime. The gateway side must bind that action token to the provider targets it
+may mutate, for example with `SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS` in the Slack
+gateway.
 
 ## Spritz Open Integration
 

integrations/slack-gateway/.env.example

@@ -17,6 +17,7 @@ SPRITZ_SLACK_BOT_SCOPES=app_mentions:read,channels:history,chat:write,im:history
 SPRITZ_SLACK_ACK_REACTION=eyes
 SPRITZ_SLACK_REMOVE_ACK_AFTER_REPLY=true
 SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN=fill-me
+SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS=T_example:C_example
 SPRITZ_SLACK_PRESET_ID=zeno
 
 SPRITZ_SLACK_BACKEND_BASE_URL=https://backend.example.com

integrations/slack-gateway/channel_actions.go

@@ -21,14 +21,10 @@ func (g *slackGateway) handleSlackReactionAction(w http.ResponseWriter, r *http.
 		writeJSON(w, http.StatusMethodNotAllowed, map[string]any{"error": "method_not_allowed"})
 		return
 	}
-	if strings.TrimSpace(g.cfg.ChannelActionsToken) == "" {
+	if len(g.cfg.ChannelActionTokens) == 0 {
 		writeJSON(w, http.StatusNotFound, map[string]any{"error": "channel_actions_disabled"})
 		return
 	}
-	if !g.authorizeChannelActionRequest(r) {
-		writeJSON(w, http.StatusUnauthorized, map[string]any{"error": "unauthorized"})
-		return
-	}
 	defer r.Body.Close()
 	var payload slackReactionActionRequest
 	decoder := json.NewDecoder(r.Body)
@@ -45,6 +41,10 @@ func (g *slackGateway) handleSlackReactionAction(w http.ResponseWriter, r *http.
 		writeJSON(w, http.StatusBadRequest, map[string]any{"error": "missing_required_field"})
 		return
 	}
+	if !g.authorizeChannelActionRequest(r, payload.TeamID, payload.ChannelID) {
+		writeJSON(w, http.StatusUnauthorized, map[string]any{"error": "unauthorized"})
+		return
+	}
 
 	ctx, cancel := context.WithTimeout(r.Context(), g.cfg.HTTPTimeout)
 	defer cancel()
@@ -86,16 +86,28 @@ func (g *slackGateway) handleSlackReactionAction(w http.ResponseWriter, r *http.
 	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
 }
 
-func (g *slackGateway) authorizeChannelActionRequest(r *http.Request) bool {
+func (g *slackGateway) authorizeChannelActionRequest(r *http.Request, teamID, channelID string) bool {
 	header := strings.TrimSpace(r.Header.Get("Authorization"))
 	token, ok := strings.CutPrefix(header, "Bearer ")
 	if !ok {
 		return false
 	}
-	expected := strings.TrimSpace(g.cfg.ChannelActionsToken)
 	token = strings.TrimSpace(token)
-	if token == "" || expected == "" || len(token) != len(expected) {
+	if token == "" || strings.TrimSpace(teamID) == "" || strings.TrimSpace(channelID) == "" {
 		return false
 	}
-	return subtle.ConstantTimeCompare([]byte(token), []byte(expected)) == 1
+	for _, candidate := range g.cfg.ChannelActionTokens {
+		expected := strings.TrimSpace(candidate.Token)
+		if expected == "" || len(token) != len(expected) {
+			continue
+		}
+		if subtle.ConstantTimeCompare([]byte(token), []byte(expected)) != 1 {
+			continue
+		}
+		if strings.TrimSpace(candidate.Target.TeamID) == strings.TrimSpace(teamID) &&
+			strings.TrimSpace(candidate.Target.ChannelID) == strings.TrimSpace(channelID) {
+			return true
+		}
+	}
+	return false
 }

integrations/slack-gateway/config.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"encoding/json"
 	"fmt"
 	"net/url"
 	"os"
@@ -21,7 +22,7 @@ type config struct {
 	SlackBotScopes             []string
 	AckReaction                string
 	RemoveAckAfterReply        bool
-	ChannelActionsToken        string
+	ChannelActionTokens        []channelActionToken
 	PresetID                   string
 	BackendBaseURL             string
 	BackendFastAPIBaseURL      string
@@ -42,6 +43,16 @@ type config struct {
 	InstallationPolicyCacheTTL time.Duration
 }
 
+type channelActionToken struct {
+	Token  string
+	Target channelActionTarget
+}
+
+type channelActionTarget struct {
+	TeamID    string
+	ChannelID string
+}
+
 func loadConfig() (config, error) {
 	cfg := config{
 		Addr:                       envOrDefault("SPRITZ_SLACK_GATEWAY_ADDR", ":8080"),
@@ -56,7 +67,6 @@ func loadConfig() (config, error) {
 		SlackBotScopes:             splitCSV(envOrDefault("SPRITZ_SLACK_BOT_SCOPES", "app_mentions:read,channels:history,chat:write,im:history,mpim:history,reactions:write")),
 		AckReaction:                normalizeSlackReactionName(envOrDefault("SPRITZ_SLACK_ACK_REACTION", "eyes")),
 		RemoveAckAfterReply:        parseBoolEnv("SPRITZ_SLACK_REMOVE_ACK_AFTER_REPLY", true),
-		ChannelActionsToken:        strings.TrimSpace(os.Getenv("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN")),
 		PresetID:                   strings.TrimSpace(envOrDefault("SPRITZ_SLACK_PRESET_ID", defaultSlackPresetID)),
 		BackendBaseURL:             strings.TrimRight(strings.TrimSpace(os.Getenv("SPRITZ_SLACK_BACKEND_BASE_URL")), "/"),
 		BackendFastAPIBaseURL:      strings.TrimRight(strings.TrimSpace(os.Getenv("SPRITZ_SLACK_BACKEND_FASTAPI_BASE_URL")), "/"),
@@ -76,6 +86,15 @@ func loadConfig() (config, error) {
 		PromptRetryTimeout:         parseDurationEnv("SPRITZ_SLACK_PROMPT_RETRY_TIMEOUT", 8*time.Second),
 		InstallationPolicyCacheTTL: parseDurationEnv("SPRITZ_SLACK_INSTALLATION_POLICY_CACHE_TTL", 10*time.Second),
 	}
+	channelActionTokens, err := parseChannelActionTokens(
+		os.Getenv("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN"),
+		os.Getenv("SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS"),
+		os.Getenv("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN_BINDINGS"),
+	)
+	if err != nil {
+		return config{}, err
+	}
+	cfg.ChannelActionTokens = channelActionTokens
 
 	if cfg.PublicURL == "" {
 		return config{}, fmt.Errorf("SPRITZ_SLACK_GATEWAY_PUBLIC_URL is required")
@@ -130,6 +149,78 @@ func loadConfig() (config, error) {
 	return cfg, nil
 }
 
+func parseChannelActionTokens(legacyToken, legacyTargets, bindingsRaw string) ([]channelActionToken, error) {
+	tokens := make([]channelActionToken, 0)
+	legacyToken = strings.TrimSpace(legacyToken)
+	for _, rawTarget := range splitCSV(legacyTargets) {
+		if legacyToken == "" {
+			return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS requires SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN")
+		}
+		target, err := parseChannelActionTarget(rawTarget)
+		if err != nil {
+			return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TARGETS is invalid: %w", err)
+		}
+		tokens = append(tokens, channelActionToken{Token: legacyToken, Target: target})
+	}
+
+	bindingsRaw = strings.TrimSpace(bindingsRaw)
+	if bindingsRaw == "" {
+		return tokens, nil
+	}
+	var bindings []struct {
+		Token   string `json:"token"`
+		Targets []struct {
+			TeamID    string `json:"teamId"`
+			ChannelID string `json:"channelId"`
+		} `json:"targets"`
+	}
+	if err := json.Unmarshal([]byte(bindingsRaw), &bindings); err != nil {
+		return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN_BINDINGS is invalid JSON: %w", err)
+	}
+	for index, binding := range bindings {
+		token := strings.TrimSpace(binding.Token)
+		if token == "" {
+			return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN_BINDINGS[%d].token is required", index)
+		}
+		if len(binding.Targets) == 0 {
+			return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN_BINDINGS[%d].targets is required", index)
+		}
+		for targetIndex, rawTarget := range binding.Targets {
+			target := channelActionTarget{
+				TeamID:    strings.TrimSpace(rawTarget.TeamID),
+				ChannelID: strings.TrimSpace(rawTarget.ChannelID),
+			}
+			if target.TeamID == "" || target.ChannelID == "" {
+				return nil, fmt.Errorf("SPRITZ_SLACK_CHANNEL_ACTIONS_TOKEN_BINDINGS[%d].targets[%d] is invalid", index, targetIndex)
+			}
+			tokens = append(tokens, channelActionToken{Token: token, Target: target})
+		}
+	}
+	return tokens, nil
+}
+
+func parseChannelActionTarget(raw string) (channelActionTarget, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return channelActionTarget{}, fmt.Errorf("target is empty")
+	}
+	separators := []string{":", "/"}
+	for _, separator := range separators {
+		teamID, channelID, ok := strings.Cut(raw, separator)
+		if ok {
+			target := channelActionTarget{
+				TeamID:    strings.TrimSpace(teamID),
+				ChannelID: strings.TrimSpace(channelID),
+			}
+			if target.TeamID == "" || target.ChannelID == "" {
+				return channelActionTarget{}, fmt.Errorf("target %q must be TEAM%sCHANNEL", raw, separator)
+			}
+			return target, nil
+		}
+	}
+	return channelActionTarget{}, fmt.Errorf("target %q must be TEAM:CHANNEL or TEAM/CHANNEL", raw)
+}
+
 func defaultReactBaseURL(publicURL string, spritzBaseURL string) string {
 	spritzBaseURL = strings.TrimRight(strings.TrimSpace(spritzBaseURL), "/")
 	if !isPrivateServiceBaseURL(spritzBaseURL) {