Relationships
#4555 Slackwater: the reference Slack app, linking people and acting for them through serve's HTTP routes
Opened by skunk-ape · 11/9/2026
Part of #4459, as item 9. Needs #4529, which has shipped. Lives in swamp-club/slackwater.
Problem
Serve can now link a person to an integration and let an app act for them within a ceiling, and a production check proved it with a script. Nothing yet shows a customer what a real integration looks like: how it links people, acts for them, handles a gate decided in a chat message, and copes with expired tokens, retries and refusals. Slackwater is that example, as a Slack app, and the first app we use ourselves.
Approach
- Deno and TypeScript, with Slack's Bolt for JS (
npm:@slack/bolt) in Socket Mode, so it runs beside serve with no public URL. - It calls serve's HTTP routes directly, through one small, readable module (
/api/v1/delegations/and/api/v1/action). It doesn't import swamp-lib, which is AGPL-only. That module is also the part a customer ports to another language, so it should read as documentation of the protocol. - A Slack app manifest in the repo. The app's display name must not contain "Slack".
Scope
- Link:
/swamp linkstarts a link with the integration credential, passing the person's Slack team, user and email. The consent URL goes only to that person, as an ephemeral message. The app polls redeem at the interval serve gives until it's issued, refused or expired, then stores the tokens under the Slack team and user. - Run:
/swamp run <workflow>runs it as the person. The idempotency key comes from the Slack interaction, so a retry from Slack replays the run rather than starting a second one. The app posts the run in the channel. - Gates: when a run it started suspends at an approval gate, the app posts Approve and Reject buttons carrying the run, step and
suspendedAt. A click decides as the person who clicked, using their own link. The message then shows who decided. A stale button, a gate already decided, and a refusal each get a clear ephemeral reply. - Status: the app polls run history for the runs it started until they settle, and updates the message.
- Unlink:
/swamp unlinkends the person's link on serve. - Not linked: anything from a person with no link replies with how to link.
- Tokens: refresh before expiry and after a 401, one refresh at a time per person. A refused refresh means the link has ended: the app forgets the tokens and asks the person to link again.
- Storage: tokens go through a small store interface. A local implementation is enough here, and the README says where to keep them in production.
- Setup: a README that takes someone from nothing to a working app:
- register an integration with a narrow ceiling and
--require-email-match - start serve in oauth mode
- create the Slack app from the manifest
- run Slackwater
- register an integration with a narrow ceiling and
Rules
- Answer Slack within its 3-second limit, and make serve calls after that.
- The consent URL is shown only to the person it's for, and never logged.
- Credentials, tokens and consent URLs never reach logs, messages or error text.
- The app never decides who may do what. Serve decides, and the app reports serve's refusal.
- Every serve call has a timeout.
- Config comes from the environment. Commit only
.env.example, and turn on GitHub secret scanning and push protection. - Add a
SECURITY.mdthat points reports to swamp's usual channel. The licence waits on the team, and the repo stays private until it's settled.
Out of scope
Installing into other workspaces (HTTP mode and Slack OAuth), an event stream instead of polling, 7b, and Enterprise Grid.
Done when
- In our Slack workspace, against a serve for
skunk-ape-test, a person links, runs a gated workflow, and a linked person approves it from the button, and the message updates. - A second linked person's click decides as them, and a refusal from serve shows as a reply.
- A Slack retry doesn't start a second run, and a stale button records nothing.
- Expired access tokens refresh by themselves. A refused refresh asks the person to link again.
- Unlinking refuses the person's next action.
- Unit tests cover the serve client module against a mock serve, and the Slack handlers against mocked Slack and serve.
- The README's setup works for someone new, step by step.
Closed
No activity in this phase yet.
skunk-ape commented 11/10/2026, 5:33:59 PM
Shipped to main in swamp-club/slackwater at 9fb3758 (private, Apache 2.0).
What's there
src/serve/client.ts: every serve call (/api/v1/delegations/links,redeem,refresh,end, and/api/v1/action) with request and reply types, written to be copied. No swamp library dependency.- A Bolt app in Socket Mode:
/slackwater linkgives an ephemeral consent button; per-automation slash commands from a commands file open a Slack form and run the workflow as the person; Approve and Reject decide gates as whoever clicks, sendingsuspendedAt. Serve decides every permission. - Tokens are wrapped so they never reach logs, messages or errors, and are kept in an encrypted store. Every serve call has a timeout. Config comes from the environment; only
.env.exampleis committed.SECURITY.mdand a README walkthrough are included.
Evidence
- 43 unit tests against a mock serve and a fake Slack: stale button, already decided, refusal, Slack retry, refused refresh, unlinked person, another workspace. Every handler test ends with a leak check.
- Live test of the action route against a real serve: idempotent replay,
gate_reopened,already_decided, approval resumes the run. - End to end against serve in OAuth mode with swamp-club, in a test Slack workspace: link,
/scale-webform, approve, run finishes. Serve's audit trail records the person andintegration:slackwateras the client. - CI (lint, types, tests, gitleaks) passed on 9fb3758.
Learned along the way
- An admin's authority doesn't carry through an integration; admins need explicit grants.
- A workflow with inputs needs
autoResume: truefor an approval to resume it. - Serve keeps no audit events without an
auditsection in its config.
The demo workflow fakes AWS for now; a real Auto Scaling demo is deferred. The lifecycle record stops at verification passed: swamp-club's attestation format is specific to swamp's own verify tooling, so none was posted for this repo.
Sign in to post a ripple.