Relationships
#4487 Slackwater: swamp-club link page, consent and the link email
Opened by skunk-ape · 11/6/2026· Shipped 11/7/2026
Part of #4459. Needs the spike in #4475, which has shipped. This is swamp-club work and can run alongside integration registration in swamp.
Problem
A person linking an app to serve needs to prove who they are and see exactly what they're agreeing to. swamp-club already hosts sign-in and SSO, so it should host this too. The device grant can't be reused: it carries only a client ID and scope, has one global 30-minute lifetime, shows only a code, and hands the poller a full swamp-club session that a link doesn't need.
The spike ran this flow end to end on throwaway code. This issue builds it for real.
Scope
API, called by serve. Each call uses Authorization: Basic <client_id:client_secret>. The client must be registered to a collective, and everything is scoped to that client. swamp-club never calls serve, and the app never talks to swamp-club.
| Call | Sends | Returns |
|---|---|---|
POST /api/v1/serve/links |
integration {id, name}, ceiling {version: 1, ceiling: [{actions, resource}]}, ceilingDigest, external {platform, team_id, user_id, display, workspace, email?}, requireEmailMatch |
requestId, one-time consentUrl, digest, expiresIn, interval |
GET /api/v1/serve/links/{requestId} |
Nothing | status: pending, approved, denied, expired or refused. When approved, also digest and identity {sub, email, username, collectives, groups} |
POST /api/v1/serve/links/{requestId}/report |
outcome: recorded, or refused with a reason |
ack, linkId |
GET /api/v1/serve/links/changes?since=<cursor> |
Cursor | ended link IDs, next cursor |
POST /api/v1/serve/links/people |
linkIds |
For each: state and identity, with collectives limited to the serve's collective |
Consent page, beside /device, on the same login and SSO path. It shows the serve, integration, ceiling, and the Slack user and workspace, in plain language.
Link email, naming the workspace and username, with a "this wasn't me" action.
Rules
- The page says what each action allows.
runmust read as starting and cancelling runs of the workflow, including runs other people started (#4485), rather than just "run". - The page shows only swamp-club's stored copy, and names the collective and instance hostname from swamp-club's own records. Client names are free text and not unique, so a name alone isn't enough.
- The digest covers the serve, integration, ceiling, external identity and a nonce. Approval must present it, and a mismatch is refused.
consentUrlis single use, stored hashed, and lasts 10 minutes. Opening it doesn't consume it, so a link preview can't use it up.- A forwarded URL is a known risk. Any signed-in person can approve, and the approver becomes the linked person. When the app supplies an email claim that doesn't match, the page warns. With
requireEmailMatch, it refuses. A wrong claim must fail safe, refusing the real owner rather than linking anyone else. collectivesis limited to the serve's collective, unlikeuserinfo.groupsstays a flat list for now, so a person's groups from another collective's IdP can still reach a serve. Document this limit.- No swamp-club session reaches serve. Serve's client credential reads only the people linked to it.
- A report is idempotent on
requestId, with a unique index. A retried report returns the samelinkIdand queues no second email.GETstays readable until the report succeeds, so a lost acknowledgement can be retried. ackmeans the link is recorded and its email queued, in one durable step. It doesn't promise delivery, and this needs a durable email queue. If the queue is down, the report fails and no link exists.- The "this wasn't me" action needs a confirming POST. Opening the email's link must not end anything, because mail scanners open links. A confirmed action ends the link, and it then appears on the change feed.
- Scoped reads: another serve gets a 404 for a request and an empty list for people. A wrong secret gets a 401.
Failures to test
| Step | Failure | swamp-club does |
|---|---|---|
| Start | Bad credential | 401 |
| Start | Missing external identity | 400 |
| Consent | Not signed in | Redirects to login and SSO, then back |
| Consent | Details changed after display | 409 |
| Consent | Email mismatch with a match required | 403, stays pending until expiry |
| Consent | Denied | denied |
| Consent | URL expired | Page 410, expired |
| Consent | Second approval | 409 |
| Report | Outcome is refused | refused, no link, no email |
| Report | Email queue down | 503, no link, no email |
| Report | Acknowledgement lost | Retry returns the same link, with one email |
Not tested in the spike
These need real coverage here, because the spike didn't reach them:
- SAML. An SP-started login should follow the same
callbackURLas OIDC, but this is read from the code. An IdP-started login lands on/signed-inwith no consent path, which is fine as long as it doesn't break. - Real email delivery. The prototype recorded emails rather than sending them.
- TLS or a proxy in front of the flow.
- A production build. Test SSO on one, because the Vite dev client reloads the page during the username step and loses the redirect.
OIDC SSO did reach the consent page in a browser, for an existing SSO user and for a new one who also chooses a username.
Out of scope
Serve's side: starting links, recording delegations, issuing tokens and polling the change feed. Those belong to the delegation item under #4459. Membership lookup for ordinary sign-ins also stays out of scope.
Done when
- A registered serve can request a link, read the result, report it and read changes, and every call is scoped to its client.
- SSO reaches the consent page over OIDC and SAML, on a production build.
- The page names the serve, collective, hostname, integration, ceiling, and Slack user and workspace, from swamp-club's stored copy.
- For a ceiling allowing
run, the page says this includes cancelling other people's runs. - The email names the Slack workspace and username, goes out only after serve reports the link was recorded, and is sent exactly once across retries.
- "This wasn't me" ends the link only after confirmation, and the link then appears on the change feed.
- Each failure in the table above has a test.
- The people read returns only that serve's linked people, with collectives limited to its own.
- swamp-uat covers the page and email against a local swamp-club.
- The manual explains what a person sees when linking, and what "this wasn't me" does.
Shipped
Click a lifecycle step above to view its details.
system commented 11/6/2026, 7:22:13 PM
Classified automatically when this issue was filed.
- Source: Swamp Club
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.