Relationships
#4622 Open serve links to every collective on an active trial or paid plan, replacing the built-in list and SERVE_LINKS_COLLECTIVES
Opened by skunk-ape · 11/10/2026· Shipped 11/11/2026
Part of #4459, as the step 8 row. Needs #4498 and #4563, which have shipped, and the security review's fixes. #4607, #4608 and #4609 have shipped. #4610 is being fixed, and this mustn't reach production before it ships. The serve side is #4623.
Problem
Serve links are gated by collective. serveLinksEnabledFor (lib/app/serve-link/serve-link-enabled.ts) allows two built-in collective ids, skunk-ape-test and skunk-ape (added by #4544), plus any ids listed in SERVE_LINKS_COLLECTIVES. For every other collective, POST /api/v1/serve/links, GET .../capabilities and the consent decision answer 404, so no customer can link people to an integration. The list was a temporary measure until the security review. Links are meant to be a feature of any collective on an active trial or paid plan.
Decision
Integration delegation links are open only to collectives on an active trial or a paid plan: collectiveStanding kinds trial and paid (any plan). admin, the standing of our own internal collectives, also qualifies, as it does at every other paygate. Nothing else does: a Personal License (licensed) never enables integration delegation, and neither do former-customer, trial-ended or no-trial. The built-in list and the env list go.
When a collective's standing lapses (a trial ends, a subscription is cancelled), its live links end through the change feed, and new links and consent are refused. A collective that regains standing doesn't get its ended links back: people link again.
Proposed change
- Replace
serveLinksEnabledForwith a check oncollectiveStanding(lib/domain/billing/standing.ts), the standing every paygate already asks. It allowstrial,paidandadminonly, as one named function with a test per standing kind. The check moves from a synchronous id match to an async lookup of the collective and its subscription, so the three call sites change: the start route, the capabilities route anddecide-link.ts. Each already takes an injectableenabledFor. - Check standing when a link starts and again at consent, so a trial that ends while a link is pending can't be approved.
- Ending links on a lapse. A trial's end is computed from dates, so no event marks it. Check standing whenever serve's client reads
changesorpeople, which it does every poll (about 30 seconds), and on any other link route. If the collective no longer stands, end its live links with a new reason,plan_lapsed, stored and public, so they appear in the nextchangespage. Also end them when a subscription is cancelled, if the billing path has a hook for it. Ending is idempotent, so racing polls end each link once. Pending link requests are withdrawn. - What serve sees. The feed's public
endedReasonisdisownedorothertoday, and serve records anything butdisownedasclub_ended. So ending through the feed works with today's serve, unchanged. Serve then recordsplan_lapsedasclub_endeduntil it learns the new reason. That's in the sibling swamp issue below. - Refusals. A collective without standing gets 403
links_require_planfrom start, capabilities and consent, with a message naming the trial or a paid plan, instead of today's 404. Serve passes it to the app. Today serve reads a 404 from capabilities as "this swamp-club has no link routes". - Status, report, changes, people, end and "this wasn't me" keep answering whatever the standing, so revocation stays visible.
- Remove
BUILT_IN_COLLECTIVE_IDSandSERVE_LINKS_COLLECTIVES. Keep one switch,SERVE_LINKS=off, that refuses every new link and consent, as an emergency stop. The currentoffvalue ofSERVE_LINKS_COLLECTIVESdoes this today. - Before deploying, confirm that
skunk-ape-testandskunk-apehave admin, paid or trial standing, so our own links keep working. - Update
AGENTS.md's environment table,CLAUDE.md,docker/club-compose.ymlandtests/support/serve-links-env.ts. Tests set standing instead of the env list. - Sibling swamp issue: serve passes
links_require_planthrough to the app with its message, and recordsplan_lapsedends as their own cause in audit andaccess delegation show. A serve without it still ends the links (asclub_ended). Check what today's serve answers the app on a 403 from capabilities or start: it must refuse the link, not report swamp-club as down. - swamp-uat's club helpers set
SERVE_LINKS_COLLECTIVESfor seeded collectives (src/club/helpers/server_runner.ts). Give seeded collectives a trial instead. That needs a sibling swamp-uat change, landing with this.
Done when
- A collective on an active trial or a paid plan can start a link, see capabilities and consent, with no list or env change.
- A test covers every
collectiveStandingkind and shows that onlytrial,paidandadminare allowed. Every other kind, includinglicensed,former-customer,trial-endedandno-trial, is refused at start, capabilities and consent. - A collective with any other standing, including a Personal License, is refused at start, capabilities and consent with 403
links_require_plan. - When a trial ends or a subscription is cancelled, the collective's live links appear as ended (
plan_lapsed) on the nextchangesread, pending requests are withdrawn, and serve refuses their tokens, tested end to end with today's serve. Regaining standing doesn't bring them back. - Standing is checked again at consent, with a test where the trial ends between start and consent.
SERVE_LINKS=offrefuses every new link and consent.- No collective id is hard-coded, and
SERVE_LINKS_COLLECTIVESis gone from code, compose files and docs. - The swamp-uat club helpers seed standing instead of the env list, and the UAT club suite passes.
Out of scope
Pricing, which plan tiers include links, and anything else the security review asks for, which gets its own issues.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.