fix(sts): key the ADK token cache by acting subject, not session alone (Python) - #2333

…e (Python) (kagent-dev#2460)

Supersedes kagent-dev#2333 (auto-closed by stale-bot; a rebase onto main
conflicted with the resource/audience support, so GitHub would not let
it be reopened).

Ref kagent-dev#2181. The Go counterpart is kagent-dev#2459 and carries the closing
reference.

## Problem

Same bug as the Go plugin: the cache was keyed by session ID alone, so a
session shared by several subjects reused whichever caller's exchanged
token was cached first.

## Change

Key the cache by `(session_id, caller credential)`, the credential
hashed. `before_run_callback` resolves the caller before the cache
lookup, so each caller gets its own exchanged token.

## What the key is derived from

The caller part comes from the inbound `Authorization` header, not from
`get_subject_token`. That hook receives the whole session state, so an
implementation reading a session-scoped field returns the same value for
every caller and collapses the key back to one entry per session. With
no inbound credential the hook's output stands in for the caller: that
mode has no per-caller identity to preserve, and keying on the header
alone would drop propagation entirely.

The key hashes the raw token rather than its `iss`/`sub`. A cache hit
returns a delegated token without an exchange, and nothing on this path
verifies a signature, so a forged token carrying a victim's claims would
select the victim's entry. Hashing the raw token makes it a cache miss,
so it reaches the STS and fails there. The cost is one extra exchange
when a caller's bearer rotates mid-session.

## Cache lifetime

An entry never outlives the credentials it rests on: `expiry` is the
earliest `exp` of the exchanged token, the pre-exchange subject token
and the caller (the inbound bearer, or the hook's token when there is
none), and both `header_provider` and the sweep refuse an entry past it.

When no token states an `exp` there is no expiry, and nothing may invent
one. The entry carries a second field, `evict_after`, which bounds
memory alone and is renewed on use.

## Per-invocation outcome

The cache only serves reuse across runs. `before_run_callback` records
each invocation's outcome, the entry it resolved or its refusal, keyed
by `invocation_id`, and `header_provider` serves that record alone,
still checked against `expiry`. Another run caching an entry for the
same caller cannot undo a refusal, and the sweep or a capacity eviction
cannot strip a run in flight of its token. `after_run_callback` and
`on_run_error_callback` drop the record. ADK calls neither for a
cancelled run, so records are bounded per session (32) and across
sessions (1024), least recently used first; a run whose record is
dropped injects no credential, logged at warning level.

## Cache capacity

The cache is bounded per session (`MAX_ENTRIES_PER_SESSION`, 32) and
across sessions (`MAX_CACHE_ENTRIES`, 1024), the same bounds as the Go
plugin. The per-session bound is what matters: without it, one session
presenting many distinct credentials evicts the entries of unrelated
sessions, and `before_run_callback` does not run again for a run that is
between tool calls. The whole-cache bound backstops it so that many
sessions cannot grow the cache without limit.

Both bounds evict the least recently used entries first. A run in flight
keeps its own token either way; the evicted caller's next run exchanges
again. Unlike the sweep, a capacity eviction drops credentials that are
still valid, so it is logged at warning level.

## Failing closed

`header_provider` injects no headers when there is no invocation
context, no record for the invocation, a recorded refusal, or an expired
entry. `before_run_callback` records a refusal and drops the caller's
cache entry on every path where it refuses to propagate: no resolvable
subject token, a failed actor fetch, or a rejected exchange.

Injecting nothing is not a denial. ADK merges the provider's headers
with the ones the toolset already carries, so a toolset configured with
its own `Authorization` header still reaches the backend under that
identity.

## Scope

Propagate-only mode (no STS configured) forwards the caller's own token.
This fix stops one caller's token reaching another, but does not add
exchange, audience narrowing or an `act` claim to that mode: there is no
STS to exchange with when none is configured.

---------

Signed-off-by: QuentinBisson <[email protected]>
Signed-off-by: Quentin Bisson <[email protected]>