# Gateway request provenance

Every request sent to the LLM gateway carries a description of what caused it:
the kind of run, the machine it came from, and the session it belongs to.

The gateway authenticates upstream with one shared credential per provider and
reaches it from one address, so a request arriving there says nothing about
which workload produced it. A test, an unattended dispatch, and a person at a
terminal are indistinguishable. Provenance is what separates them, in the
records the gateway already keeps.

The fields, and how each one is obtained, are in
[`packages/cf-harness/README.md`](../../packages/cf-harness/README.md#request-provenance).
This document holds the invariants behind them.

## One vocabulary, two senders

`cf-harness` sends provenance on every gateway request it makes. Toolshed sends
it on the gateway requests its `/api/ai/llm` routes and its web search make;
[`packages/toolshed/README.md`](../../packages/toolshed/README.md#gateway-request-provenance)
says what it reports.

Both build their headers from `packages/cf-harness/src/provenance.ts`, which
toolshed imports as `@commonfabric/cf-harness/provenance`. One implementation
means one sanitizer, and it means a field cannot exist for one sender and not
the other. The `User-Agent` opens with the name of the sending program, so the
two are told apart by user agent alone.

The gateway names each header it handles. A Lua filter copies the names it
knows into dynamic metadata, and a patch policy removes those names from the
request; both lists are written out in the infra repository, under
`k8s/manifests/envoy-gateway/`. Neither is a prefix match. A field added to
`provenanceEntries` and not to those lists travels to the model vendor and
appears in no log, so a new field is two changes across two repositories.

The gateway requires the invoker, principal and session headers on every
request to its LLM hostname. It returns HTTP 400 before forwarding upstream
when any of the three is absent or empty. Browser CORS preflights do not
require provenance.

## Two channels, one set of values

The values travel twice: as `x-cf-harness-*` headers, and condensed into the
`User-Agent`.

The `User-Agent` is the channel that works against the gateway as deployed. Its
Envoy access log records the user agent of every request, and nothing else that
identifies a caller, and that log reaches Cloud Logging. The headers carry the
same values for a reader that names them in an access-log field.

## What a value may contain

These headers reach the upstream provider along with the request. Two invariants
follow.

**A value carries no request content.** Nothing derived from a prompt, a
message, a tool argument, or a command line appears in one. Three mechanisms
hold this: the `command` field is mapped through a closed set, so an
unrecognized harness argument reports `prompt` and a toolshed request reports
the name of the operation it is performing; every value passes through a
sanitizer, at
the one point where values leave, that bounds it to a short run of characters
that cannot break a header or carry structure into one; and a Loom run manifest
contributes only its dispatch class.

The sanitizer bounds a value rather than inspecting it. What keeps request
content out is the closed set `command` is drawn from: no other field is fed
from a prompt, a message, or a command line.

**A value identifies no person.** Where a signal is a unique identifier of a
person or of their machine, only its presence is read: a coding agent's marker
variable says which agent is running, and its contents stay on the machine.

One value does name a single execution. Under continuous integration the `ci`
field carries the workflow and run identifier, which resolves to one run in that
system's records. That is deliberate, and it is the field's purpose: it is what
makes a run's traffic findable afterwards. It names an automated execution, and
the identifier is already recorded against that run by the system that produced
it.

## The principal is not derivable from the machine

A principal names the machine a request came from. It is generated by
`crypto.getRandomValues` on first use and kept in the harness home, so nothing
about the machine determines it.

This is a requirement rather than an artifact of the implementation. The
identifying values a machine offers are its account name and its hostname.
Across a team those form a space of a few hundred candidates, and a commodity
laptop searches about a hundred thousand candidates a second, which puts any
value computed from them within milliseconds of recovery. The size of that input
space is what governs, so a wider output does not move it.

This invariant is also why no real principal appears in any document in this
repository. A principal published next to the name of whoever committed it is
tied to a person for good.

A principal that cannot be stored is reported as `unstable-<label>`. It lasts
for one process, so grouping by it undercounts, and the name says so.

## The service is named by itself, and nothing else is inferred

The `service` field names the service that launched the harness. It is read
from that service's own `OTEL_SERVICE_NAME`, which it sets to name itself for
tracing and which every process it spawns inherits, so a harness a service
launches reports both the service invoker and the service's name without
further configuration.

Nothing else about the surroundings is inferred. No filesystem path and no git
metadata contributes to any field. Two facts constrain that. A checkout's path
describes the layout of one machine. A checkout's git remote names the project
the code came from: Loom vendors labs as a full clone whose origin is labs, so
a Loom-driven run carries labs as its remote.

An absent field means the value was not there to read.

## A server reports itself, not the caller behind it

A field describes the process that sent the request. For `cf-harness` that
process is the workload, so the two coincide. Toolshed is a server: one process
serves many callers, and its session groups the requests of one toolshed
process rather than the requests of one caller.

Naming the caller behind a toolshed request means the caller naming itself.
Nothing in a request to `/api/ai/llm` says which space or which piece it came
from: the runner's LLM builtins send neither, and `packages/llm/src/client.ts`
sends no provenance of its own. Until they do, toolshed has nothing to report,
and reporting a guess would be worse than reporting nothing.

Such a field is internal metadata. A space identifier names one of our spaces,
which a model vendor has no use for, and a space is often one person's, so it
carries the identification the fields here are built to avoid. It reaches the
gateway only under a header the gateway removes by name, which is the change
across two repositories described above.

## Coverage

Four gaps are known.

Subagents share their parent's gateway client, so their requests carry the
parent's session. Separating them takes a per-turn mechanism; the client holds
one provenance for its lifetime.

A principal covers one harness home. A person running the harness from a laptop
and a dev box has a principal for each, and a home that is wiped starts a new
one. A server's principal is the one its container holds, which a container
that starts with an empty filesystem draws afresh; `CF_HARNESS_PRINCIPAL` pins
it to the deployment instead.

Toolshed reports the route a request came from as its command, and reports it
for as long as the route's call is being awaited. A streaming response is read
by its caller after that call returns, so the requests the model makes to
continue a tool-calling conversation over that stream report no command.

Toolshed reports no space and no piece, for the reason above.

The Codex transport is out of scope: it addresses a different endpoint under a
personal subscription, and sends its own originator and session headers.