The token asserts caller identity, not humanity: enforce aud, and rename

[adamjohnwright]

Builds on #239 (which must merge first — same branch lineage). The website session answered D1 and corrected the premise it rested on.

D1: the question had a false premise

There is no human gate on the search path, and there is not going to be one — nobody solves a captcha to run a search. Their only hCaptcha belongs to the contact form and is spent on submit. So a token here cannot honestly assert a human is present, and asking it to would have meant inventing a claim.

It asserts caller identity instead: minted server-side per request, EdDSA, with iss, aud, iat, exp at +120s, and sub — an opaque per-visit id of 128 random bits holding nothing about the reader. Our backstop limit already keys on sub, so that part needed no change.

Abuse control moved with the premise: their panel is opt-in behind a click, so a crawled search never reaches a model, and their proxy rate limits by address.

The audience check was worse than missing

They asked us to enforce aud. We passed none — and PyJWT rejects a token carrying aud when no audience is expected:

token	expected	result
aud=reactome-chatbot	reactome-chatbot	accepted
aud=elsewhere	reactome-chatbot	InvalidAudienceError
no aud	reactome-chatbot	MissingRequiredClaimError
aud=reactome-chatbot	none	InvalidAudienceError ← today

So the endpoint would have refused every token they minted. The first real one would have failed and looked like a signing problem. aud is now required and checked against reactome-chatbot, overridable via CALLER_TOKEN_AUDIENCE — which falls back rather than honouring an empty value, since an empty expectation refuses every real token instead of loosening the check.

MissingRequiredClaimError now names the claim; it reported "token has no expiry" for whatever was missing, which would have misreported a missing audience.

Renamed throughout

human_token now says something untrue about the security model, and only one consumer exists to update — they have not started building. Module, tests, request field (caller_token), env var (CALLER_TOKEN_PUBLIC_KEY_PATH), compose secret, key files, the beta script, and the specs.

A test also changed meaning rather than just names: test_the_limit_is_per_caller used two tokens differing only in expiry and expected them to count separately. With sub, that is wrong — they mint one token per request, so keying on the token would make the limit meaningless. It now uses two visits, and pins that a freshly minted token for the same visit does not buy a fresh allowance.

Their cancellation question, measured

They asked whether a dropped proxy connection abandons the run. It does: a client hang-up raises CancelledError inside the answer generator and nothing further is produced — 3 tokens read, 3 produced, then cancelled. They need not cancel upstream. Recorded in the contract.

Verified on the served path

Real app, renamed env var, tokens shaped like theirs: a website-shaped token answers in 19.9s; a wrong audience and a missing audience are both refused in 0.0s.

CI-equivalent locally: ruff, format, mypy (129 files), full suite with no API keys set.

🤖 Generated with Claude Code