Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

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, approve and signal.
  • Delegation: a person's consent for an integration to act for them, tied to their external identity (for Slack, team_id and user_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 idempotencyKey per user action, and a gate decision carries suspendedAt, 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 run doesn't imply approve.
  • 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}]}, with workflow: selectors that can end in a wildcard. Its digest is sha256: 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 delete and data rename refuse 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):

  1. The person runs /swamp link in Slack, and the app asks serve to start a link.
  2. Serve sends swamp-club the integration, ceiling and Slack identity, and gets a one-time URL. The app shows it only to that person.
  3. Serve polls swamp-club while the person signs in and reads a consent page naming the serve, integration, ceiling, Slack user and workspace.
  4. Once the person approves, serve receives their identity, checks admission and records the delegation.
  5. 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.
  6. 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-match stays 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 run should name specific workflows.
  • A ceiling allowing run also allows cancelling any run of that workflow, including another person's, because run carries 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.
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

11/5/2026, 10:02:44 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.