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

Relationships

#4460 Slackwater: record the client on requests, audit events and run decisions

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

Part of #4459. This is the first step, and it needs nothing else first.

Problem

Serve can't tell how a person's action reached it. A Principal holds only a kind and an ID, audit events record the principal, and a run records initiatedBy and each gate's decidedBy. An app acting with a person's token looks the same as that person using the CLI or the dashboard.

Serve should know this for every caller. Later work needs the record to exist first: grant conditions will read the client, and operators need to see which client did what.

The model

Each token records a client, written <kind>:<id>, separate from the principal.

  • The kind says what serve does differently. direct has no ceiling. integration will have one: the person's grants intersected with what an admin approved for that app.
  • The ID says which one, for the record. Code may read it for display and validation, but behaviour never branches on it.
How the token is issued Client
swamp auth login --server direct:cli
Dashboard login direct:dashboard
swamp access token mint direct:token
Integration link (later work) integration:<id>

The client labels how a token was issued, not what is presenting it. A copied CLI token still reads direct:cli, so direct IDs are not a security boundary.

Scope

  • Token record: gains the client. Serve sets it when it issues the token, and only reads it afterwards. It is never derived at request time and never supplied by a caller. Rotation keeps it.
  • Request context: handlers can see the client alongside the principal. The person stays the principal, so existing grant checks don't change.
  • Audit events: AuditEvent in src/domain/serve_audit/audit_event.ts gains the client.
  • Run record: src/domain/workflows/workflow_run.ts records the client that started a run and the client behind each gate decision, alongside initiatedBy and decidedBy.
  • Output: the field appears in --json, in log output where the principal already shows, in audit sinks including CEF and syslog, and in swamp audit log as a last column. swamp audit export --format csv gains a client column beside the other identity columns, so consumers must parse by header.

No production path issues an integration token until registration lands. Tests can write one on a token record.

Rules

  • The client comes only from the authenticated credential's record, never from a request payload. Add a test that a client value sent in a payload is ignored, and that a forwarded run record can't set one.
  • An absent client reads as direct with no ID. That covers tokens issued before this change until they are replaced. It never reads as "unknown", and old records load unchanged. Calls with no credential, such as schedules and webhooks, have no client either; they keep their service: principal.
  • Audit events are hash-chained. The new field must be covered by the digest, and existing chains must still verify.
  • Followers forward writes with the caller's own credentials, so a forwarded request must record the same client as a direct one on the leader.
  • A new serve must keep working with an older CLI. The feature only fully works once all sides are upgraded: an older node may drop the field when it rewrites a record, but nothing may fail because of it.

Out of scope

Registering integrations, ceilings, delegations, grant condition fields, audit filters by client, dashboard display and the HTTP route. Those are later items under #4459.

Done when

  • Audit events and run records name the client, including gate decisions, for tokens issued after this change.
  • Tokens, records and chains from before this change load and verify, and read as direct with no ID.
  • A client value in a request payload has no effect.
  • An older CLI can still resume a run whose gate a new serve decided.
  • Tests cover the rules above, including a forwarded request.
  • swamp-uat's strict JSON schemas are updated with this change wherever the new field can appear.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 12 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/6/2026, 1:22:25 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/5/2026, 10:09:08 PM

Sign in to post a ripple.