These pages describe PrivacyFence 8.0.0. Download it · What changed
The PrivacyFence identity claim (contract)¶
The contract between PrivacyFence and an upstream MCP server. It says what a signed claim contains, how
it is tied to one tool call, and what an upstream must check before it trusts it. Read it when you
write or review an upstream's verifier, or when a claim is refused and you need to know why. How an
operator declares an upstream is in upstream-mcp.md. The claim format is
claim_version 1.
Purpose¶
PrivacyFence decides who a caller is and which audiences they hold. It proves that to an upstream with a short signed claim bound to one tool call, so the upstream can enforce the audiences in its own queries. PrivacyFence holds the approvals and the audit trail; the upstream holds the data and never needs to see PrivacyFence's other state. PrivacyFence never filters an upstream's results.
Transport¶
- The claim is sent in the HTTP header
X-PrivacyFence-Claim, on every HTTP request PrivacyFence makes to the upstream's MCP endpoint, a new claim each time. One tool call is several HTTP requests (initialize,notifications/initialized,tools/call, session delete). Authorizationis never set or read by PrivacyFence. It is free for the upstream's own use.- A claim is a compact JWT (JWS). Answer
401with no detail for any failure.
The JWT¶
Header:
{"alg": "EdDSA", "kid": "<kid>", "typ": "pf-identity-claim+jwt"}
alg is exactly EdDSA (Ed25519). Refuse none, HMAC and RSA algorithms. typ is exactly
pf-identity-claim+jwt, which keeps a claim apart from the OpenID Connect tokens PrivacyFence also signs.
Payload. A key is omitted, never null, when it does not apply.
| Claim | Value |
|---|---|
claim_version |
1 (always present). |
iss |
PrivacyFence's issuer URL with no path suffix, for example https://pf.example.org. |
aud |
The audience the operator declared for this upstream. Accept only your own. |
sub |
The principal's id: the person's id, n8n-token:<token id> for a scoped token, privacyfence for a service claim. |
principal_type |
claude_client, n8n_workflow, service or human (see Principals). |
email |
The verified email. Present only when sub is a person and the address is verified. With email_for_visibility: true it is lower-cased and NFC (ASCII only: an address with a non-ASCII character gives no email). |
approved_by |
The id of the person who created the token. Present only for n8n_workflow. |
token_id |
The scoped token's id. Present only for n8n_workflow. |
act |
{"sub": <OAuth client id>, "agent": <attested agent id>} for claude_client (the RFC 8693 actor). agent only when the client is attested; sub only when known. Absent for any other type. |
audiences |
Sorted list of strings; [] when none or unresolved. Always present. |
tools |
Sorted list of the upstream's own tool names this principal may call on this upstream. Always present. Information only: never use it to decide what a query returns. |
req |
The request binding. Present on a tools/call request only (next sections). |
iat, exp, jti |
Timing and the replay id. jti is a UUID string. |
iss has no path suffix. The public keys are at <issuer>/upstream-mcp/jwks.
sub, principal_type, audiences and req may change what a query returns, and email too, but only
when the upstream declared email_for_visibility: true
(Email as a visibility input). approved_by, token_id and
act are for your own audit.
Principals¶
principal_type |
Meaning | sub |
|---|---|---|
claude_client |
A person's AI client acting for them. | The person's principal id. email is the verified address; act names the client. |
n8n_workflow |
Any scoped token, whether delivered to n8n or not. | n8n-token:<token id>. No email: a workflow does not act live for a person, so it cannot match attendee-only rows. approved_by is the creator, for audit. |
service |
PrivacyFence's own requests: the startup tool listing and, when the operator declared audiences_tool, the call of that tool. |
privacyfence, with audiences: []. Return the tool list and no data, except for the audiences tool (below). |
human |
Reserved. PrivacyFence never mints it. | Refuse it unless you have a use for it. |
An operator can limit an upstream to a subset of claude_client and n8n_workflow
(allowed_principal_types); a caller of another type is refused before anything is sent.
Audiences¶
audiences is the union of the audiences of the groups the person belongs to, from the verified email
only (an unverified or missing email gives []). all is the one unrestricted audience; every other
audience is restricted. A scoped token carries owner's audiences now ∩ the audiences chosen at creation,
so a creator who loses an audience takes it from the token on its next call.
Filter by audiences inside your own query, not afterwards, so ranking and pagination stay correct and a
guessed document id is still refused. An empty list matches no row.
For an upstream that declared audiences_tool, a person's audiences come from that tool's answer instead of the groups.
Email as a visibility input (opt-in)¶
By default email is for your audit only. An operator can make it a fifth input to what a query returns
by declaring email_for_visibility: true on the upstream (upstream-mcp.md), for
example so a knowledge hub can show an attendee-only record to the people on its attendee list. With the
opt-in on, PrivacyFence promises, for every request it signs:
emailis present only whenprincipal_typeisclaude_client. A scoped token (n8n_workflow) and aserviceclaim never carry it, opted in or not.- It is the verified address only. "Verified" is what PrivacyFence treats as verified at sign-in: the
identity provider said so, or the operator trusts unverified addresses for an allowed domain
(
PRIVACYFENCE_IDP_TRUST_UNVERIFIED_EMAIL), which makes the address count as verified for that domain. An address that is not verified gives noemail. - It is lower-cased, in Unicode NFC, and ASCII only. An address with a non-ASCII character (a look-alike
such as the Kelvin sign, or a genuine internationalised address) gives no
emailand noaudiences; the sign-in itself still works. - It comes from the same verified source and goes through the same normaliser as
audiences, so the address inemailis the address that decided the audiences. substays when the person's address changes, andemailfollows.
What the upstream does:
- Filter inside your own query by exact match of
emailagainst your own list (an attendee list, say), as foraudiences, so ranking and pagination stay correct. - Use
emailonly on atools/callwhosereqmatched. PrivacyFence also sendsemailon the other requests of a person (initialize,tools/listand so on); never return data for those. - An absent
emailmatches nothing.
An upstream that did not opt in must keep treating email as audit-only.
The audiences tool (opt-in)¶
An operator can declare audiences_tool: <name> on an upstream (upstream-mcp.md),
so that the upstream tells PrivacyFence who holds each of its audiences. PrivacyFence then sends tools/call
of <name> with {} and a service claim, at startup and on an interval. The claim's req is bound to
that call, as for any tools/call, and its tools is ["<name>"] (information only, as everywhere: never
decide on it). The upstream answers with the table only when all of these hold:
- the claim verified, and
principal_typeisserviceandsubisprivacyfence; reqmatched the request body;- the tool name in
params.nameis its own audiences tool.
Every other request with a service claim still gets no data. The answer, as structured content or as the
text of the result, is a JSON object with exactly the keys version (the number 1) and audiences (an
object of audience name to a list of addresses):
{"version": 1, "audiences": {"mgmt": ["[email protected]", "[email protected]"], "finance": ["[email protected]"]}}
It holds audience names and addresses only, never documents. Audience names are 1-63 characters (a-z,
0-9, _, -, starting with a letter or digit), at most 200 of them, at most 20000 addresses in all, and
the answer is at most 1 MB; anything else is refused as a whole, and the previous answer stays. Addresses
should be the lower-cased form of the identity provider's verified address: PrivacyFence applies the same
normaliser as for email (ASCII only) and drops, counts and ignores any address that does not pass. The
name all is an ordinary name here: the upstream may list anyone under it, and there is no approval.
A change to the shape of the answer bumps the answer's own version, not claim_version
(ADR 0326).
The request binding¶
req ties a claim to one tools/call:
req = base64url_nopad(SHA-256(canonical_request(tool, arguments)))
canonical_request is the UTF-8 bytes of
json.dumps({"tool": tool, "arguments": arguments}, sort_keys=True,
separators=(",", ":"), ensure_ascii=False, allow_nan=False)
toolis the upstream's own tool name (search, notknowledgehub_search).argumentsis theparams.argumentsobject of thetools/callrequest, withoutreason; an absent object is{}.- Keys are sorted by Unicode code point, at every depth. Separators are
,and:with no whitespace. - Non-ASCII text is written as UTF-8, never as
\uXXXXescapes. Control characters,"and\use the JSON short escapes. - Integers are decimal, with no limit on size. Other numbers use Python's shortest round-trip
repr(1.5). This is the one place another language can differ: check it against the vectors. NaNandInfinityare not valid.- Duplicate keys in the request body are refused by the verifier.
The six vectors below are the contract; they are also in
contrib/verifier/req_test_vectors.json, computed
independently of any implementation. An implementation that reproduces all six has the canonicalisation
right.
| Name | Canonical text | req |
|---|---|---|
| empty-arguments | {"arguments":{},"tool":"search"} |
_jS9stFeCkVA2Ed7FqOzjA5kl4RdO11hSbb_QDrlYEw |
| key-order-is-sorted | {"arguments":{"limit":5,"query":"policy"},"tool":"search"} |
L1g2NbgUryfvpWA8DUp2BKfiUaA39GNhc2N-7LbSmaI |
| nested-and-arrays | {"arguments":{"filters":{"a":null,"b":[3,1,2]},"id":"d-42"},"tool":"get_doc"} |
77eDoXOlibw6zBWIRyXkbHv9q8uxz-RlZvQN0u_N85w |
| unicode-not-escaped | {"arguments":{"query":"Größe café 日本語"},"tool":"search"} |
opa6QE9p8-IKxdFU_PDTAeX0wSPlUiO2_Pj8iQXi12A |
| astral-and-escapes | {"arguments":{"query":"line\nbreak \"quoted\" \\ 😀"},"tool":"search"} |
fBlyH6L_1srMHjsC-c6KcTLGRwLYc7XmaqdElibG-9Y |
| numbers-and-booleans | {"arguments":{"big":12345678901234567890,"f":1.5,"n":0,"neg":-7,"no":false,"ok":true},"tool":"list"} |
j0MCtwK9UI17zZyw2aimBWRq8vxDl5ODknEIYcJkp0M |
In the astral-and-escapes row, \n, \" and \\ are the two-character JSON escapes, and the emoji is
written as UTF-8.
What the rules mean for the upstream
- A
tools/callclaim carriesreq. Refuse atools/callwithout a matchingreq, with a different one, or areqon any other request. - Every other request (
initialize,notifications/initialized, session delete,tools/list) carriesaudiences: [],tools: []and noreq. Return no audiences for it and no data. - A JSON-RPC batch (a JSON array body) is refused. A claim covers exactly one request.
- Only the tool name and the arguments are bound.
params._metais not. Dispatch only the tool name and arguments you hashed, and ignore everything else in the request.
A captured claim therefore cannot be replayed for another call, another argument set, or a non-call request.
Lifetime and clock skew¶
exp - iat is the upstream's claim_lifetime_seconds: 5 to 60, default 60. Refuse a claim whose
lifetime is above 60 seconds or not positive. Allow clock leeway of at most 5 seconds on exp and iat.
Keep a jti cache for the claim's lifetime plus the leeway and refuse a jti you have seen.
Keys and rotation¶
- Public keys are served at
<issuer>/upstream-mcp/jwks(public, no sign-in) as an OKP/Ed25519 JWKS:{"kty": "OKP", "crv": "Ed25519", "x": ..., "use": "sig", "alg": "EdDSA", "kid": ...}. Thekidis the first 16 characters of the base64url SHA-256 of the raw public key. - The response may be cached for 300 seconds. Honor the
kid; on an unknownkid, refetch once, and not more often than every 30 seconds. - Rotation (
privacyfence-app --rotate-upstream-claim-key) publishes the new key at once but it starts signing 300 seconds later, so a verifier that caches for 300 seconds has it before it signs. The previous key keeps signing until then and stays in the JWKS for the operator's overlap (claim.key_overlap_hours, default 24 hours), so a claim already minted still verifies. --revoke-upstream-claim-key KIDremoves a key from the JWKS at once. After the cache expires and one refetch, a claim signed by it is an unknownkid.
Verification checklist¶
Do these in order and answer 401 on the first failure:
- The header
algis exactlyEdDSAandtypispf-identity-claim+jwt. - The header
kidis in the JWKS (after at most one refetch) and the key is an Ed25519 OKP key. - The signature is valid.
issequals your PrivacyFence issuer URL andaudequals your own audience.exp,iatand the leeway: not expired, not issued in the future, lifetime at most 60 seconds.claim_versionis1.principal_typeis one you know.audiencesandtoolsare lists of strings.- The request body: parse it with duplicate keys refused; refuse a batch; for a
tools/call,reqmust equal the hash of the tool name and arguments in this body; for any other request there must be noreqand you take no audiences. - The
jtihas not been seen.
claim_version and the checks above are what pf_claim_verify.py implements.
Using pf_claim_verify.py¶
contrib/verifier/pf_claim_verify.py is one file you vendor into
your server. It needs Python 3.9 or later, the standard library, PyJWT and cryptography.
from pf_claim_verify import CLAIM_HEADER, ClaimError, ClaimVerifier
verifier = ClaimVerifier(
issuer="https://pf.example.org",
audience="knowledge-hub",
jwks_url="https://pf.example.org/upstream-mcp/jwks",
)
def authenticate(headers, body: bytes):
try:
principal = verifier.verify(headers[CLAIM_HEADER], body=body)
except ClaimError as exc:
raise PermissionError(exc.code) # answer 401, log the code, never the claim
return principal # principal.audiences is () unless body is a tools/call
verify(token, *, body=b"") takes the raw request body. verify_tool_call(token, tool, arguments)
checks a call you already parsed. The returned Principal is a frozen dataclass with sub,
principal_type, email, audiences, tools, approved_by, token_id, act, jti, expires_at and
claim_version. A replayed jti is refused by default; plug a shared store in through replay_cache
(an object with add_if_new(jti, expires_at) -> bool) when you run several processes.
Row-level security sketch (PostgreSQL)¶
Set the caller's audiences once per transaction and let the database enforce them:
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents FORCE ROW LEVEL SECURITY;
CREATE POLICY documents_by_audience ON documents
USING (audience = ANY (string_to_array(current_setting('app.audiences'), ',')));
BEGIN;
SET LOCAL app.audiences = 'all,hr'; -- the claim's audiences, comma-joined, after verification
SELECT id, title FROM documents WHERE body ILIKE '%policy%';
COMMIT;
Bind the list as a parameter (SELECT set_config('app.audiences', $1, true)), never by string
concatenation. An empty list must give an empty app.audiences, which matches no row. Connect as a role
that is not the table owner and has no BYPASSRLS.
Versioning¶
This document describes claim_version 1. Adding an optional claim keeps the version at 1, so ignore
claims you do not know. An opt-in the operator declares per upstream, such as email_for_visibility,
changes nothing for an upstream that does not opt in, so it keeps the version at 1. The audiences tool is such an opt-in too: it keeps the version at 1, and a later change to the shape of its result bumps the result's own version. Once an upstream
has opted in, though, any change to how email is filled (its source, its normalisation, the cases
where it is present) is a breaking contract change: it needs claim_version 2 and a new typ. Any other change (a changed meaning, a removed or newly required claim, another
canonicalisation) is claim_version 2 and a new typ, so a verifier for version 1 refuses it by
design.