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

[Starlight143]

This feels like exactly the right fix direction.

If scope-filter decisions can outlive the token they were derived from, then the system can look healthy while silently making authorization decisions against stale context. That’s one of the hardest classes of policy failure to debug.

Binding the cached scope context to token identity seems like the minimum safe contract.

I’d probably go one step further and make the cache key conceptually include:

• token identity / fingerprint
• auth mode
• relevant actor or installation context
• any server-side capability version that affects filtering

And then fail closed on any mismatch.

A few principles here seem especially important:

1. stale scope context should never widen visibility
2. cache reuse should require an explicit identity match
3. token rotation / swap should force re-evaluation
4. 401/403 paths should be able to invalidate cached assumptions immediately
5. visible tools and callable tools should not drift apart silently

I also think this connects back to a broader MCP concern: clients benefit a lot when discovery-time hints are available, but runtime authorization must still be computed against the current token and current execution context.

So overall, this token-bound approach seems like the right operational model.

Least-privilege is much easier to reason about when cached authorization state is explicitly token-scoped and mismatch means "recompute", not "best effort reuse".

[SamMorrowDrums]

This is not the case. We don't cache. The STDIO server checks at startup and doesn't re-check, that doesn't make sense to add checks on every call, but it has no impact on auth boundary.

The http server does check every request, and supports up-scoping dynamically etc too.