Relationships
#4543 swamp-lib: link a person, act over HTTP and refresh delegated tokens
Opened by skunk-ape · 11/9/2026· Shipped 11/9/2026
Part of #4459, as item 8. Needs #4474, #4529, #4438 and #4445, which have shipped. The reference Slack app (item 9) builds on it.
Problem
swamp-lib (packages/client, @swamp-club/swamp-lib) only speaks the WebSocket API. An integration acting for a person uses serve's bearer-only HTTP routes instead: /api/v1/action for workflow actions (#4474) and /api/v1/delegations/ for links and tokens (#4529). Today every app would have to write those calls by hand, including the parts that are easy to get wrong:
- Refresh rotates. Reusing an old refresh token ends the delegation, so two requests that refresh at once can unlink the person.
- Retries need care. A start needs a stable idempotency key per user action, and a gate decision carries
suspendedAt, so a retry or a stale button records nothing new. An app that makes a fresh key on retry starts a second run. - Replies have several outcomes. A start can come back started, replayed or refused, and a decision can find the gate already decided or moved on.
Scope
- Workflow actions over HTTP: typed calls for each type in
HTTP_ACTION_TYPES: run, resume, history, approvals, approve, reject and signal. Replies are typed, with refusals, replays and stale decisions as outcomes the caller has to handle, not as generic errors. - Links: start a link, poll and redeem it for tokens, and end it, using the integration credential where serve needs it.
- Tokens: a token holder that adds the access token to each call, refreshes it before it expires and after a 401, and stores the rotated pair through a store the app provides.
- Errors: one typed error carrying serve's code and status, so an app can tell "not linked", "not allowed", "link ended" and "try again" apart.
Rules
- Refresh is single-flight. Concurrent callers for one delegation share one refresh, and the new pair is stored before any caller uses it. Test that racing calls never send an old refresh token.
- A failed refresh never retries with the old refresh token. A refusal means the link has ended, and the helper says so, so the app can ask the person to link again.
- The idempotency key comes from the caller, tied to the user action, such as a Slack interaction ID. The helper never makes one up on retry.
- Credentials and tokens never reach logs or error messages.
- Only serve's public routes. Nothing imports from
src/. Protocol types the library needs are copied intopackages/client, as today, with a test that keeps them in step with serve's. - Every outbound call takes an
AbortSignal, with a default timeout. - The existing WebSocket API keeps working, with no breaking change.
Out of scope
The Slack app (item 9), the integration's own event stream (general release), and anything 7b adds. Polling run status through the existing read route is enough for a pilot.
Done when
- An app can link a person, act for them over HTTP within the ceiling, and survive token expiry, with no hand-written HTTP.
- Racing refreshes never reuse a refresh token, and a refused refresh reports the link as ended.
- A retried start with the same key comes back replayed, and a stale approval records nothing.
- Integration tests run the library against a real serve on port 0 for links, refresh and each action type.
- The module docs show the link, act and refresh flow.
- A new swamp-lib version is published.
Shipped
Click a lifecycle step above to view its details.
system commented 11/9/2026, 2:15:21 PM
Classified automatically when this issue was filed.
- Source: Extensions
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.