Token-bound PAT scope caching to prevent stale tool filtering decisions

[davidahmann]

Problem observed

Scope-filter decisions can be wrong when a request context contains cached scopes that were computed for a different token. In that case, tool visibility may reflect old permissions after token rotation/swap, which is a quiet policy failure: behavior appears successful but authorization state is stale.

Why it matters operationally

This server is used as a permission-scoped control surface over GitHub actions. If scope filtering reuses stale context, downstream automation can act on an inaccurate capability set. That undermines least-privilege guarantees and makes incidents hard to classify (policy vs product). Token churn is common in real usage, so cache correctness has to be explicit and fail closed.

Minimal repro

go test ./pkg/context ./pkg/http/middleware ./pkg/http
# exercise middleware with context preloaded for token A, active token B
# verify middleware refetches for token B instead of reusing token A scopes

Fix approach

I introduced token-bound scope context helpers and switched filter/middleware call sites to token-bound reads:

• new context helpers: bind/retrieve scopes with token identity
• PAT middleware now reuses scopes only when token matches
• scope challenge and HTTP PAT scope filter now follow the same token-bound contract
• added regression tests for token mismatch refetch and context helper behavior

The intent is straightforward: cached scopes are only valid for the token that produced them.

Validation evidence

• go test ./pkg/context ./pkg/http/middleware ./pkg/http passed
• Added unit tests for token-bound scope retrieval behavior
• Added middleware regression test for cached-scope/token mismatch

Open follow-up question for maintainers

Would you like token fingerprints (rather than raw token string equality) used for context binding to make cross-layer logging/debug safer by default?

Inspired by research context: CAISI publishes independent, reproducible AI agent governance research: https://caisi.dev