#4459 Slackwater: let customers build integrations that drive workflows securely and auditably

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.

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

A client acts for a person, within a ceiling. Effective rights are the person's grants intersected with the client's ceiling, checked by serve on every request.

• Client: registered by an operator, with a credential and a ceiling. A ceiling can narrow rights but never add them, and can't include admin.
• Delegation: a person's consent for a client to act for them, tied to their external identity (for Slack, team_id and user_id). Only that person can create one.
• Tokens: a short-lived access token per person, with a rotating refresh token that needs the client's credential. Ending a delegation or client ends its tokens.
• Client identity: client:<id> 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 client. Polling is acceptable for a pilot.
• Separation of duties: self-approval and refusing a client are grant conditions the operator writes, not gate settings.

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 client, 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:

1. The person runs /swamp link in Slack, and the app asks serve to start a link.
2. Serve sends swamp-club the client, 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, client, 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 acknowledges that report, so a link can't become active without its email being sent.
6. The app receives the tokens and confirms in Slack.

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. The consent page and email are the main defences, and this is the main item for the security review.
• 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.
• token-mode serves have no swamp-club sign-in, so they refuse link requests for now.

Planned work

Issues are listed in dependency order and are filed only when work on them is ready to start, so this list may change.

Needed for a pilot:

1. Record the client on requests, audit events and run decisions (swamp)
2. Grant conditions can read the client and the run's initiator (swamp)
3. Bearer-only HTTP route for workflow actions (swamp)
4. Spike: delegated credentials through serve (swamp)
5. Client registration and ceiling (swamp)
6. Link page: consent and the link email (swamp-club)
7. Delegation: link requests, tokens, refresh and revocation (swamp)
8. swamp-lib: typed workflow helpers and token refresh (swamp, also needs #4438 and #4445)
9. Slackwater: the reference Slack app (new repo)
10. UAT journeys for clients, delegations and HTTP actions (swamp-uat)

A security review of the consent flow and tokens comes before any pilot.

Needed for general release:

1. Run events: filtered stream and webhook delivery (swamp)
2. Approver and verified email in run context (swamp)
3. Versioned contract and conformance suite (swamp)
4. Narrow membership and group lookup (swamp-club)
5. Customer guide: build an integration (swamp-club)
6. Client usage counts in telemetry (swamp)

Still open

• The name for the generic concept in code and on the CLI. "Client" is a working term here, and it already means other things in swamp.
• Who sets a ceiling and what it can include, how long a delegation lasts in oauth mode, and whether one link can carry across several serves.