Skip to main content
← Back to list
01Issue
FeatureShippedSwamp ClubPublic
Assigneesskunk-ape

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. run must 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.
  • consentUrl is 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.
  • collectives is limited to the serve's collective, unlike userinfo. groups stays 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 same linkId and queues no second email. GET stays readable until the report succeeds, so a lost acknowledgement can be retried.
  • ack means 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 callbackURL as OIDC, but this is read from the code. An IdP-started login lands on /signed-in with 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.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 17 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

11/7/2026, 4:19:28 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/7/2026, 1:18:05 AM
Editable. Press Enter to edit.

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.