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.
directhas no ceiling.integrationwill 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:
AuditEventinsrc/domain/serve_audit/audit_event.tsgains the client. - Run record:
src/domain/workflows/workflow_run.tsrecords the client that started a run and the client behind each gate decision, alongsideinitiatedByanddecidedBy. - Output: the field appears in
--json, inlogoutput where the principal already shows, in audit sinks including CEF and syslog, and inswamp audit logas a last column.swamp audit export --format csvgains aclientcolumn 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.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.