Relationships
#4563 Delegation: keep serve's links in step with swamp-club after linking
Opened by skunk-ape · 11/9/2026· Shipped 11/10/2026
Part of #4459, as item 7b. Needs #4529, which has shipped. It comes before a customer pilot, and the security review starts once it merges.
Problem
Since #4529, a link ended on serve reaches swamp-club, but nothing flows the other way. Serve never reads swamp-club's link feed or people read after linking, so:
- A person who ends a link on swamp-club ("this wasn't me") keeps an app acting for them on serve.
- A link swamp-club ends itself, such as when its email can't be delivered, keeps working on serve.
- A person suspended on swamp-club, or who leaves the serve's collective, keeps their delegation. #4530 refuses a person once a serve's own allowed lists drop them, but a delegation's collectives are a snapshot taken at consent, so leaving a collective on swamp-club never reaches it.
- When swamp-club refuses the serve's own client, its links carry on.
Each of these lasts until the link is ended on serve or its 30 days run out.
Separately, a ceiling an operator widens gives a delegation nothing new, which is right. But the app can't tell "outside what this person consented to" from any other refusal, and consenting again means a new link. That ends the old delegation, and with it any gated run bound to it.
Scope
- Ended links. The leader polls
GET /api/v1/serve/links/changes?since=<cursor>on an interval and ends each listed delegation, recording the cause: disowned, or ended by swamp-club. The cursor is stored in the datastore, so a new leader carries on from it. Pages are read untilmoreis false. - People. The leader reads
POST /api/v1/serve/links/peoplefor its active delegations, at most 200 link IDs a call, on a slower interval:endedends the delegation.suspendedrefuses the delegation while the suspension lasts, without ending it.activerefreshes the delegation's identity snapshot, including the collectives #4530 checks admission against. Leaving the collective then refuses the person through #4530's path.
- swamp-club refuses the serve. When the feed or people read gets
401 invalid_clientor403 client_not_collective, serve refuses every delegated request it holds and says why in the log and audit. It doesn't end the delegations, so they come back once the client is accepted again (see To settle). - swamp-club unavailable. Links keep working, no new links start, and the reads retry with backoff. This matches #4475's contract.
- Consenting again. A request outside the consented ceiling but inside the current one gets a distinct refusal,
consent_required, so an app can ask the person. Linking again for the same integration and external identity, with the wider ceiling, updates the existing delegation's consented ceiling and keeps its ID. Gated runs bound to it carry on. A narrower or equal ceiling changes nothing. - Triggers and schedules. Add a test that a delegated token can't create a trigger or a schedule.
Rules
- Every change applies without a grant reload, on the leader and through a follower, and closes that delegation's sockets and streams, as ending does today.
- Only the leader polls. A follower sees the result through the datastore.
- The reads use serve's own client credential and hold no swamp-club session.
- A suspended or refused delegation refuses refresh as well as requests, and refresh succeeds again only once the state clears.
- Audit each end, suspension, refusal and consent update, with the cause. Never log a token or credential.
- Every swamp-club call has a timeout.
To settle
- Poll intervals. Recommendation: the feed every 30 seconds, matching serve's other access polls, and people every 5 minutes.
- A long refusal of serve's client. Recommendation: refuse while it lasts, and end every delegation if it lasts past the access token life (1 hour). A revoked client should not leave links that come back months later.
Out of scope
The Slack app (#4555), an event stream for integrations, and anything the security review asks for.
Done when
- Against a local swamp-club, ending a link there ("this wasn't me") refuses its next request on serve within one feed interval, on the leader and through a follower.
- A link swamp-club ends on an undeliverable email is ended on serve the same way.
- A suspended person is refused, then works again once the suspension lifts. A person who leaves the collective is refused.
- swamp-club refusing serve's client refuses every delegated request. swamp-club being down leaves links working and refuses new ones.
- A new leader carries on from the stored cursor without missing or repeating an end.
- With a widened ceiling, a request outside the consented ceiling gets
consent_required. Linking again keeps the delegation ID, a gated run bound to it resumes, and the new action is allowed. - A delegated token is refused when creating a trigger or a schedule.
- Property tests show the delegation state machine never moves out of ended, across random sequences of feed, people and refusal events.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.