Pipelock v2.2.0 extends the proof story from logs and receipts onto the request path itself.
When mediation_envelope.sign is enabled, Pipelock can attach a signed mediation envelope to proxied HTTP and MCP traffic so downstream systems can verify what policy mediated the request.
What the envelope carries
The mediation envelope is sideband metadata that tells the downstream system things like:
- action
- verdict
- actor identity
- policy hash
- receipt correlation
- taint state
- task ID
Without signing, that metadata is still useful, but it is just a header or _meta field. With signing, the downstream verifier can check that the envelope was produced by Pipelock and not rewritten along the way.
Why this matters
This is useful when the downstream system needs more than a log line after the fact.
Examples:
- an internal gateway that wants proof a request passed through the expected policy
- an approval service that needs the policy hash and action before it accepts a side effect
- an audit pipeline that wants verifiable mediation metadata without scraping logs
In those cases, unsigned metadata is not enough.
Signing model
Pipelock uses RFC 9421 HTTP Message Signatures with an Ed25519 signing key.
The important operator-facing details are:
- signing is opt-in
- startup fails closed if signing is enabled without a readable key
- reload also fails closed if the new signing key cannot be read
- the policy hash is canonicalized so formatting noise does not change it
That last point is what makes the policy hash useful for downstream verification. Reformatting the YAML should not look like a behavior change. Real behavioral changes still move the hash.
Configuration shape
At a high level, enable:
mediation_envelope:
enabled: true
sign: true
signing_key_path: /path/to/ed25519-key
key_id: pipelock-prod
The exact envelope and signing fields live in the upstream configuration reference, but the operational point is simple: do not turn signing on until the key path, reload behavior, and downstream verifier expectations are all understood.
HTTP and MCP behavior
For HTTP traffic, the envelope is attached as a Pipelock-Mediation header.
For MCP traffic, the envelope is attached in _meta["com.pipelock/mediation"].
In both cases, Pipelock strips forged inbound envelope and signature members before adding its own. That keeps caller-supplied mediation claims from bleeding through as if they were trusted.
Redirects and downstream verification
v2.2.0 also refreshes the envelope on allowed redirects, so redirect legs carry the right target, hop count, and signature state instead of stale metadata from the original request.
That matters because downstream verifiers are only useful if the signed envelope still matches the actual request they received.
When to turn this on
Enable mediation-envelope signing when:
- downstream services already care about policy provenance
- you are integrating Pipelock into an approval or admission workflow
- you want stronger cross-service evidence than unsigned headers
Do not enable it just because the feature exists. If nothing downstream verifies the envelope, you are adding key management without using the proof.