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

Relationships

#4486 Slackwater: integration registration and ceiling

Opened by skunk-ape · 11/6/2026· Shipped 11/7/2026

Part of #4459. Needs #4460 and the spike in #4475, which have shipped. Can run alongside the swamp-club link page.

Problem

Serve can record that a token belongs to an integration, but it has no way to register one or to limit what it can do. A person's token used through an app can do everything that person can.

An operator needs to register an integration and give it a ceiling. A person's effective rights through it are then their grants intersected with that ceiling, checked by serve on every request.

Scope

  • Integration: a new aggregate holding its ID, name, credential, ceiling and state (active or revoked).
  • Ceiling: a new value object listing allowed actions and resource selectors. It can narrow rights but never add them.
  • Commands: swamp access integration can register, list, show and revoke an integration and change its ceiling, in log and --json modes. The credential is shown once, at registration.
  • Enforcement: a principal whose client is integration:<id> is limited by that integration's ceiling on every decision. An unknown or revoked integration is refused.
  • Ceiling digest: a stable digest of a ceiling, which the delegation item will use to tell whether a ceiling has widened since a person consented.

Nothing in production issues integration tokens yet, so tests write the client on a token record, as they did for #4460. The spike found that an older node gives a delegated token the person's full authority, so the delegation item must add a capability check before any link starts.

Rules

  • Enforce in one place. Do it inside GrantBasedAccessDecisionService, not in handlers. The spike showed this covers the request paths with no handler changes.
  • A ceiling refusal is an explicit deny. Several sites fall back to an admin check when a decision is null, so a null would let an admin person through. Test that an admin person with an empty ceiling is refused.
  • Actions match literally. Grants let run imply approve, and in the spike a ceiling allowing only run approved a real gate. A ceiling allows only the actions it names.
  • A ceiling covers only workflow: resources for now. Registering or changing a ceiling refuses any other resource kind, including behaviors, so an integration token can't run a behavior directly on any transport. Vault access rework may widen this later.
  • A ceiling can allow only run, read, approve and signal. It refuses write, tag and admin. In the spike, a write ceiling created a schedule that kept firing after the link ended. A later change can add an action safely, and removing one can't be done safely.
  • Rights a person has only because they're an admin aren't available through an integration, and only their explicit grants count. Document this.
  • Use new record types, not grant rows. A grant with a new subject kind stopped an older serve from starting at all, because it couldn't load its policy. Integrations must be records an older node ignores, and they must reach followers through the commit feed.
  • Changes apply without a grant reload. --grant-reload manual is the default, and it holds grant changes until a reload. Revoking an integration or narrowing its ceiling must apply without one.
  • The credential is stored hashed.
  • Vault use during a run has no ceiling, in line with #4473's rule that client conditions never narrow a run. Starting the run is where a ceiling applies. Document this limit, and that a ceiling allowing run should name specific workflows.
  • run in a ceiling includes cancel. Since #4485, run on a workflow allows cancelling any run of it, including another person's or a scheduled one, and there's no separate action to narrow this. Cancelling a parent also cancels its suspended children, on workflows the ceiling doesn't name. --restricted-commands workflow.cancel keeps cancel away from integration tokens, because that check needs admin and a ceiling can't allow it. Document all of this.
  • /api/v1/health answers any valid token, including one with an empty ceiling. This was decided in the spike.
  • The datastore API and dashboard session exchange refuse integration tokens.

Keeping it complete

The spike sent all 131 WebSocket request types with an empty ceiling. 119 were refused, and 12 had no ceiling check on that run. Of those, nine were accounted for, while commits.subscribe, commits.head and workflow.signal weren't exercised.

  • Exercise those three.

  • Add a rule test that walks ServerRequestSchema with an empty ceiling, so a new request type can't skip the check without being listed.

  • List the transports an integration token may use, and test each: WebSocket, HTTP read route, the #4474 action route, HTTP cancel, HTTP signal, and the admin routes.

  • Keep the existing rule test that behaviour never branches on a client ID. A ceiling lookup is keyed on the ID, so state how that fits the rule, and change the test only as far as this needs.

  • Test that a vault expression in workflow inputs stays inert for an integration token through serve, on both workflow.run and workflow.evaluate. This was only checked on a local CLI run, and the workflow-only ceiling relies on it.

Out of scope

Link requests, delegations, tokens, the link page, refusing triggers and schedules for integration tokens, and the capability check. Those belong to the delegation and link page items under #4459.

Done when

  • An operator can register, list, show and revoke an integration and change its ceiling.
  • A request above the ceiling is refused even when grants allow it, and a request within both is allowed.
  • A ceiling allowing only run doesn't allow approve.
  • An admin person with an empty ceiling is refused, and the refusal is audited with the principal and client.
  • A revoked integration is refused at once, without a grant reload, on the leader and through a follower.
  • An older node given these records still loads its policy.
  • The rule test walks every request type, and each exempt type is listed with a reason.
  • Effective access has property tests: across random policies a ceiling never widens rights, and an unknown integration fails closed.
  • An integration token with run in its ceiling can cancel a run of that workflow. One without it gets the same 404 as a missing run, and the refusal is audited with the principal and client.
  • With --restricted-commands workflow.cancel, an integration token is refused a cancel on both routes, even when the person is an admin.
  • A ceiling naming another resource kind, or write, tag or admin, is refused when written.
  • With the widest ceiling allowed, an integration token is refused every behavior request on every transport, even when the person's grants allow it.
  • swamp-uat covers the commands against the compiled binary, with its strict JSON schemas updated.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 46 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/7/2026, 8:20:41 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/7/2026, 1:17:48 AM

Sign in to post a ripple.