Relationships
#4459 Slackwater: let customers build integrations that drive workflows securely and auditably
Opened by skunk-ape · 11/5/2026
Goal
Customers can build integrations that drive swamp workflows securely and auditably. Slack is the proving case, through a reference app code-named Slackwater, but it isn't the end goal: the same surface should serve any integration.
A Slack button that runs or approves something must be at least as safe as the CLI path it replaces.
This is the umbrella issue. Work items are filed one at a time, when we're ready to start each one. The list below is kept current.
Planned work
Needed for a pilot
Each step can start once the one before it has merged. Issues in the same step can run at the same time.
| Step | # | Issue | Repo | Needs | Status |
|---|---|---|---|---|---|
| 1 | 1 | #4460 Record the client on requests, audit events and run decisions | swamp | None | Shipped |
| 2 | 2 | #4473 Grant conditions can read the client and the run's initiator | swamp | 1 | Shipped |
| 2 | 3 | #4474 Bearer-only HTTP route for workflow actions | swamp | 1 | Shipped |
| 2 | 4 | #4475 Spike: delegated credentials through serve | swamp | 1 | Shipped |
| 2 | #4438 workflowRun never settles at an approval gate |
swamp | None | Shipped | |
| 2 | #4445 workflowRunStream drops a refusal |
swamp | None | Shipped | |
| 2 | #4484 Security report, follow-up to #4473 | swamp | 2 | Shipped | |
| 2 | #4485 workflow approvals offers a cancel that serve refuses without admin, follow-up to #4473 |
swamp | 2 | Shipped | |
| 3 | 5 | #4486 Integration registration and ceiling | swamp | 1, 4 | Shipped |
| 3 | 6 | #4487 Link page: consent and the link email | swamp-club | 4 | Shipped |
| 4 | 7a | #4529 Delegation: link a person to an integration and issue their tokens | swamp | 5, 6 | Shipped |
| 5 | 7b | #4563 Delegation: keep serve's links in step with swamp-club after linking | swamp | 7a | Shipped |
| 5 | #4498 Security report: rotating a collective's OAuth client secret, keeping or ending links | swamp-club | None | Shipped | |
| 5 | 8 | #4543 swamp-lib: link a person, act over HTTP and refresh delegated tokens | swamp | 3, 7a, #4438, #4445 | Shipped |
| 5 | #4544 Enable serve links for skunk-ape-test without an environment change | swamp-club | 7a | Shipped | |
| 5 | #4554 Serve-link copy, the username step, switching account, and withdrawn-link copy, in one pass (absorbs #4589's copy; its manual fix moved to #4619) | swamp-club | 6 | Shipped | |
| 5 | 10 | UAT journeys for integrations, delegations, links and keeping links in step, absorbing swamp-uat#909 (swamp-uat#929) | swamp-uat | 3, 5, 7a, 7b | Merged |
| 6 | 9 | #4555 Slackwater: the reference Slack app | swamp-club/slackwater | 7a | Done |
| 7 | Security review of the consent flow and tokens | swamp, swamp-club, slackwater | 7b, #4498 | Done | |
| 7 | #4607 Security report, finding F1 | swamp-club | Review | Shipped | |
| 7 | #4608 Security report, finding F2 | swamp-club | Review | Shipped | |
| 7 | #4609 Security report, finding F3 | swamp | Review | Shipped | |
| 7 | #4610 Security report, finding F4 | swamp | Review | Shipped | |
| 7 | #4626 A serve set up through the normal OAuth path can't link people: its client isn't a collective's | swamp | 7b | Shipped | |
| 7 | 15 | #4619 Manual: build your own integration with swamp serve, using Slackwater as the reference, plus the serve manual corrections | swamp-club | 9, #4626 | Shipped |
| 7 | #4645 A link request withdrawn by a plan lapse is stored with the secret-rotation reason | swamp-club | #4622 | In progress | |
| 8 | #4622 Open links to every collective on an active trial or paid plan, replacing the #4544 list and SERVE_LINKS_COLLECTIVES |
swamp-club | #4498, 7b, #4610 | Shipped | |
| 8 | #4623 serve: pass swamp-club's links_require_plan refusal to the app, and record links ended by a lapsed plan |
swamp | #4622 | Shipped |
Customers build and run their own Slack apps and other integrations. Slackwater is a reference to help them build one; we don't host an app. A first Slack app, used inside our own collective, needed 7a and 9. Both work: an end-to-end demo was recorded on 2026-11-10 against skunk-ape-test. Slackwater calls serve's HTTP routes directly rather than through swamp-lib, which is AGPL-only, so a customer can copy it without taking on that licence. Slackwater itself is licensed Apache-2.0, and its repo is public at https://github.com/swamp-club/slackwater (2026-11-11). swamp-lib (item 8) remains for TypeScript apps that can. 7b and #4498 shipped on 2026-11-10.
7b (#4563) shipped what happens after linking: serve reads swamp-club's change feed, so "this wasn't me" and links swamp-club ends reach serve within about 30 seconds, and its people read, so suspensions and leaving the collective do too. While swamp-club refuses serve's client, serve refuses every delegated request, and ends the links once it reads swamp-club again or the refusal has lasted an hour. A person can consent again to a wider ceiling without ending the delegation, and a delegated token is refused when it creates a trigger or schedule. #4498 lets a collective rotate its OAuth client secret either keeping links, with both secrets working until the old one is removed, or ending them. Its UAT is swamp-uat#924. #4589 updates the manual's leaked-secret steps to match 7b.
UAT for the link page (#4487) is on hold as swamp-uat#909, and the strict schemas #4529 and 7b wrote for access delegation output wait on an unpushed swamp-uat branch. Item 10 picks up both. #4487 is deployed, and the production check below confirmed real email delivery.
#4529 ships links only for a collective swamp-club has enabled, and #4544 enables skunk-ape-test. A production check passed on 2026-11-09 against stable 7285a656: an app linked a person, the link email arrived, and the app ran and approved a gated workflow as that person within its ceiling. A workflow outside the ceiling and a stale approval were refused, refresh worked, and ending the link refused its tokens. #4554 tidied the copy that check turned up.
The collective gate is gone. Since #4622, links are open to collectives on an active trial or a paid plan, and our own admin collectives. A personal collective qualifies when its owner is a member of a collective on a trial or a paid plan, as with private extensions, so a Personal License on its own never enables integration delegation. Any other collective gets 403 links_require_plan, which serve (#4623) passes to the app. When a collective's standing lapses, its live links end through the change feed, recorded as plan_lapsed. A serve whose swamp-club client isn't a collective's, such as one set up through the browser device approval, can't link: since #4626 the app gets 409 links_require_collective_client rather than club_unavailable. Serves that link people are set up with a collective API key ("Deploy with Headless OAuth").
A security review of the consent flow and tokens comes before any pilot. It ran on 2026-11-10, against customers running their own apps, and reported four findings, filed as private security reports #4607, #4608, #4609 and #4610. #4607 and #4608 have shipped in swamp-club. #4609 and #4610 have shipped in swamp. Of the issues it was asked to settle, #4584 has shipped, and #4499 was deferred: hashing client secrets adds little while session and OAuth tokens are stored the same way, and rotation (#4498) now covers a leaked secret. #4479 and #4503 stay in the general-release list, and #4496 matters only if a pilot serve runs in team mode. #4482 was fixed by #4530.
Needed for general release
These wait for the pilot, though 12, 14 and 16 aren't blocked by other work. Item 16 is filed as #4683 and #4684 (2026-11-12): today linking is recorded only in swamp-club's database, adding an integration reaches us not at all, and actions through an integration arrive without saying so. The customer guide (15) moved to the pilot list as #4619, because customers build their own apps from it.
| # | Issue | Repo | Needs | Status |
|---|---|---|---|---|
| 11 | Run events: filtered stream and webhook delivery | swamp | 1, 5 | Not filed |
| 12 | Approver and verified email in run context | swamp | 1 | Not filed |
| 13 | Versioned contract and conformance suite | swamp | 3, 11 | Not filed |
| 14 | Narrow membership and group lookup for sign-ins (delegations get this from #4487) | swamp-club | Works with #4388 | Not filed |
| 16 | #4683 serve: telemetry for integrations: report hosted integrations to swamp-club, a client kind on usage events, and events for approvals and run control | swamp | None | Open |
| 16 | #4684 swamp-club: store the integrations each serve reports, and send serve-link events to analytics | swamp-club | Works with #4683 | Open |
| #4479 Security report, vault access in runs | swamp | None | Open | |
#4674 Dashboard: show the client (e.g. integration:slackwater) on activity events and run details |
swamp | None | In progress | |
| #4499 Security report, follows #4498 | swamp-club | #4498 | Closed: deferred | |
| #4584 Security report, follow-up to #4498 | swamp-club | #4498 | Shipped | |
| #4365 serve takes a rotated OAuth client secret without a restart, and says when its client is refused | swamp | #4498 | Open | |
#4585 OAuth clients can't complete authorization_code (redirect URIs stored as JSON) |
swamp-club | None | Open | |
| #4586 Audit OAuth client deletion | swamp-club | #4498 | Open | |
| #4614 Security report, follow-up to #4609 | swamp | None | Open | |
| #4615 Security report, follow-up to #4584 | swamp | None | Open | |
| #4616 Security report, follow-up to #4584 | swamp-club | None | Open |
Why this looks achievable
A test Slack app against a local serve started a run, refused a person without the right grant, approved as the linked person, and recorded both identities correctly. It used serve's existing handlers. Sign-in was a stand-in, so real consent and delegated tokens are unproven, as are the HTTP action route, oauth mode, and TLS or a proxy.
Design
Names. Every token records a client, written <kind>:<id>. The kind is direct or integration, and only the kind changes what serve does. An app an admin registers is an integration, managed with swamp access integration. Slackwater names this project and its reference app.
An integration acts for a person, within a ceiling. Effective rights are the person's grants intersected with the integration's ceiling, checked by serve on every request.
- Integration: registered by an operator, with a credential and a ceiling. A ceiling can narrow rights but never add them. For now it covers only workflows, and can allow only
run,read,approveandsignal. - Delegation: a person's consent for an integration to act for them, tied to their external identity (for Slack,
team_idanduser_id). Only that person can create one. - Tokens: a 1-hour access token per person, and a refresh token that needs the integration's credential. Since #4543, refresh mints a new access token and keeps the refresh token, so racing refreshes are harmless. A delegation lasts 30 days from consent and is never extended. Runs bind to the delegation rather than the token, so a new access token doesn't break a gated run. Ending a delegation or integration ends its tokens. Serve holds no swamp-club session for a delegation.
- The integration's own identity: can read events within its grants and ceiling, but can't run or approve.
- Transport: bearer-only HTTP for actions, and one event stream per integration. Polling is acceptable for a pilot. The route (#4474) requires a stable
idempotencyKeyper user action, and a gate decision carriessuspendedAt, so a retry or a stale button records nothing new. - Separation of duties: self-approval and refusing an integration are deny grants the operator writes, not gate settings. These shipped in #4473.
- Ceiling enforcement: in one place, inside the access decision service. Integrations and delegations are their own record types, not grant rows, so an older node ignores them. Ceiling actions match literally, so
rundoesn't implyapprove. - Widening a ceiling needs new consent, by comparing the ceiling with a stored copy of what the person agreed to. A digest shows that a ceiling changed, but not whether it widened. Narrowing applies at once, without a grant reload.
- Ceiling format:
{version: 1, ceiling: [{actions, resource}]}, withworkflow:selectors that can end in a wildcard. Its digest issha256:over the RFC 8785 form, and #4487's link digest covers it, so changing those bytes affects both. - Integration credential: generated by the CLI and stored as a SHA-256 hash, with no rotation yet.
- Revoking is final, except for overlapping writes. A revoked ID stays reserved, and
model delete,data deleteanddata renamerefuse an integration's record. This ships independent of v3, so on a store with one cache per machine (a v2 bucket, the default), overlapping writes are last write wins, and a register can bring back a just-revoked ID. Through serve, that window can last until the next poll, 30 seconds by default. A commit-log datastore refuses it. This limit comes from reading the code: serve peers with separate caches and overlapping writes haven't been tested. - Routes an integration token can't use: the datastore API,
commits.*and the dashboard session exchange. - Older nodes: one that predates client records or integrations gives a delegated token the person's full authority, so a link can't start unless every live instance reports support for it. That check has to land before any token is issued.
swamp-club proves who the person is, and serve decides what they may do. swamp-club hosts sign-in, SSO, the consent page and the link email, on the same landing pages sign-in uses today. Serve keeps the integration, ceiling, delegation and every allow or deny decision.
The app only ever calls serve, and serve only makes outbound calls to swamp-club, so this suits a serve with no public address. After linking, actions don't call swamp-club.
Linking a person. A link has its own flow beside the device grant, on the same login and SSO pages (#4475):
- The person runs
/swamp linkin Slack, and the app asks serve to start a link. - Serve sends swamp-club the integration, ceiling and Slack identity, and gets a one-time URL. The app shows it only to that person.
- Serve polls swamp-club while the person signs in and reads a consent page naming the serve, integration, ceiling, Slack user and workspace.
- Once the person approves, serve receives their identity, checks admission and records the delegation.
- Serve reports the link to swamp-club, which emails the person. No tokens are issued until swamp-club has recorded the link and queued its email. Reports can be retried safely, and redeeming a link is once only.
- The app receives the tokens and confirms in Slack.
If the person says "this wasn't me" in the email, serve learns of it by polling a per-serve change feed, so swamp-club never calls serve.
Known limits
- A compromised app can act for the people linked to it, within its ceiling, until it's revoked. Any integration outside serve has this limit.
- A forwarded one-time URL could link the sender's Slack account to the person who approves it. Since #4607, the consent page and email say plainly that approving lets the app act as you, and when the app's email doesn't match the approver's, approving needs a "this account is mine" confirmation. An app that sends no email is protected by that wording alone. A return code tying completion to the starting account (#4617, #4618) was considered and declined, so the guide tells app authors to send the person's email, and
--require-email-matchstays available for strict matching. - Work already under way can outlive a link: a started run carries on, and only later requests are refused. Integration tokens are refused on triggers and schedules, so nothing new can be left behind.
- A ceiling can't reach inside a workflow: once a run starts, its steps have no further grant checks. A ceiling allowing
runshould name specific workflows. - A ceiling allowing
runalso allows cancelling any run of that workflow, including another person's, becauseruncarries cancel (#4485). Cancelling a parent also cancels its suspended children, on workflows the ceiling doesn't name. An operator can keep cancel away from integrations with--restricted-commands workflow.cancel. token-mode serves have no swamp-club sign-in, so they refuse link requests for now.- Ending a link with the CLI on a serve's host, rather than through serve with
--server, refuses refresh at once, but an access token already issued keeps working until serve's next delegation poll, up to 30 seconds. This is accepted. - A link ended on swamp-club ("this wasn't me", an undeliverable email), a suspension or a person leaving the collective reaches serve at its next poll, about 30 seconds by default, not at once.
Still open
- What happens to a suspended run when its sign-in token is revoked.
- How revoked integration IDs get cleaned up, since they stay reserved and their names can't be reused.
- What a revoke does during a network partition. This hasn't been tested. With the leader stopped and storage up, a follower kept answering reads for up to 99 seconds, because the staleness limit didn't apply.
- Whether a ceiling can limit vault use during a run. #4486 merges without this, and #4479 picks it up for general release.
- Whether one link can carry across several serves.
Open
No activity in this phase yet.
Sign in to post a ripple.