Relationships
#4529 Delegation: link a person to an integration and issue their tokens
Opened by skunk-ape · 11/8/2026· Shipped 11/9/2026
Part of #4459, as item 7a. Needs #4486 and #4487, which have shipped. The rest of delegation, keeping links in step with swamp-club afterwards, is item 7b and follows this.
Problem
An operator can register an integration and give it a ceiling (#4486), and swamp-club can show a consent page and send the link email (#4487). Nothing connects them yet: serve can't start a link, record that a person consented, or issue the tokens an app uses to act for that person. So no integration can act for anyone.
Scope
- Starting a link. An app, authenticated with its integration credential, asks serve to start a link for an external identity (for Slack,
team_idanduser_id). Serve starts one with swamp-club and returns the one-time consent URL for the app to show only to that person. - Finishing it. Serve polls swamp-club for the result, checks the digest it got at the start, checks the person is admitted, records the delegation and reports it. The app then redeems the link for its tokens.
- Delegation: a new aggregate holding the person, integration, external identity, the ceiling the person consented to, expiry and state (active or ended).
- Tokens: a short-lived access token for the person, and a rotating refresh token that needs the integration's credential.
- Ending a link: by the person through the app, by an operator, or by revoking the integration, which ends all of its delegations.
- Commands:
swamp access delegationcan list, show and end delegations, inlogand--jsonmodes.
Rules
- Check capabilities before any link. An older node gives an
integration:token the person's full authority (#4475, #4486). Serve refuses to start a link unless every live instance reports that it supports links, and the check lands before any token is issued. Instance heartbeats need to carry capabilities for this. - An older node must not honour a delegated token. Choose a token record an older node reads as not found, or a state value it fails to parse, so it fails closed. Test this on the released binary.
- Check the integration credential. Starting a link, redeeming and refreshing all need it. Nothing checks it today.
- Close overlapping registers first. Overlapping
registercalls can all report success, and only the last write's credential matches. On a v2 bucket, a register that overlaps a revoke can bring the ID back with a new credential hash. #4486 added no HA lock in its layer. Make sure no credential check can pass for a register that lost, or for an ID that was revoked, and test it with separate caches per machine. - Follow #4475's link contract as #4487 shipped it: serve calls swamp-club with its client credential, swamp-club never calls serve, and no token exists until swamp-club has recorded the link and queued its email.
- A retried report gets the same link and no second email.
- Redeeming is atomic and once only. In the spike, racing polls first got three tokens.
- Pending requests live in the datastore, so any node can carry one on.
- Effective rights are the person's grants, intersected with the integration's current ceiling and with the ceiling the person consented to. Narrowing applies at once. A wider ceiling gives nothing until the person consents again, which comes with 7b.
- Runs bind to the delegation, not the token. Rotating the token doesn't break a gated run, and a resume after the delegation ends is refused. A schedule's next run fails once the link that created it has ended.
- Serve keeps no swamp-club session for a delegation. It reads what it needs with its own client credential.
- Ending a delegation applies without a grant reload, on the leader and through a follower, and closes that delegation's sockets and streams. Runs already started carry on. Serve calls swamp-club's
/endfor that link so its state matches. - A
token-mode serve refuses a link request with a clear error. - Audit every start, consent result, refusal, issue, refresh and end, with the principal, client and delegation. Never log a token or credential.
To settle
- Maximum life of a delegation. Refresh keeps it alive, so it needs a fixed limit. Recommendation: 30 days, matching today's sign-in token, and the person links again after that.
- Access token life. Recommendation: 1 hour.
- One delegation per external identity. Recommendation: linking again for the same integration and external identity ends the old delegation.
Out of scope
Keeping links in step with swamp-club after linking is 7b: the change feed for "this wasn't me", polling /people for suspensions, treating a 403 from swamp-club as every link having ended, consenting again to a wider ceiling, and a test that creating triggers and schedules is refused. Also out of scope: swamp-lib helpers (item 8) and the Slack app (item 9).
Done when
- Against a local swamp-club, an app starts a link, the person consents, and the app redeems tokens that act as that person within the ceiling.
- Redeeming twice, or from racing polls, gives one set of tokens. A lost report acknowledgement retried gives one link and one email.
- Each failure row in #4475's contract table refuses, and leaves no token.
- Refreshing rotates the refresh token, and a reused refresh token is refused.
- A wrong or revoked integration credential is refused at start, redeem and refresh. A register that lost an overlap doesn't pass.
- A link is refused while any live instance lacks support, and a delegated token is refused on the released binary.
- A gated run started through a link survives token rotation and is refused on resume after its delegation ends.
- Ending a delegation, or revoking its integration, refuses the next request at once, without a grant reload, on the leader and through a follower.
- A widened ceiling gives a delegation nothing new.
- Property tests show that across random policies and ceilings, a delegated principal never gets more than grants intersected with both ceilings.
- The UAT on hold as swamp-uat#909 is re-read against what this ships, and its tests run here or move to item 10.
- With
SERVE_LINKS_COLLECTIVESset to our own collective, a link works end to end against production swamp-club, and the link email arrives.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.