[claude-tmgbedu]

Summary

Lets an app guard routes with user = Depends(Auth.guard("auth.api")), where the guard config decides how the user is resolved.

• Auth.guard(name) / AsyncAuth.guard(name) on the class returns a GuardDependency. It resolves the user through the named guard and raises 401 when none is found. Dependencies with the same name compare equal, so app.dependency_overrides[Auth.guard("api")] works. On an instance, auth.guard(name) still returns the guard object.
• New ChainGuard(guards=[...]) driver tries its members in order, e.g. a bearer token, then the browser session. A bearer token the request presents is final: if the token member rejects it, the chain fails rather than falling back to the session.
• OAuth2Guard(first_party_only=True) refuses tokens issued to an OAuth client (client_id set).
• AuthManager.on_authenticated(listener) runs listener(request, user, guard) after a guard dependency resolves a user and before the handler. Apps use it for activity tracking and request state.

Upgrade note

Inside a request, class-level Auth.guard() used to return the guard. To get the guard there now, use Depends(Auth.scoped) or the manager.

Tests

tests/test_guard_dependency.py covers:

• valid, missing and invalid tokens
• client-credentials tokens
• chain fallback, and no fallback after a rejected token
• first-party-only guards
• dependency overrides
• listeners
• chain config errors
• async chains

The full suite and ruff pass.

Salut Keera needs this to remove its local auth. A release is needed before the app can pin a version from PyPI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H45FAaoDKkVZYFVvML9Ya4

[claude-tmgbedu]

Review: CHANGES REQUESTED

Head reviewed: ad300399fb2712149e5582718edf1ed88941329c. Full suite and ruff check . pass locally.

What works: GuardDependency resolves through the named guard and raises 401. Equal names compare and hash equal, and I checked that FastAPI caches two Depends(Auth.guard("x")) on one route, so the guard runs once. first_party_only, chain config validation, async chain selection and the on_authenticated hook all look correct.

Blocking

1. src/fastapi_startkit_auth/facade.py:17-23 (GuardAccessor) breaks existing callers. On v0.7.0, class-level Auth.guard("api") inside a request goes through ScopedMethod and returns the guard. After this PR it returns a GuardDependency, so code like Auth.guard("api").provider or .user_from_token(...) / .authenticate(request) now fails with AttributeError. The task asked for the dependency and for the guard proxy to keep working inside a request. Fix: have GuardDependency forward unknown attributes to the guard inside an active request, for example __getattr__ → current_auth_request().manager.guard(self.name). Add a test showing that Auth.guard("api").provider still works inside a request.
2. src/fastapi_startkit_auth/guards/chain.py:88-89 (_rejected_presented_token): the rule "a presented bearer token is final" only works for oauth2 members. It treats a member as a token guard only when the member has no authenticate method. TokenGuard (driver: "token") has authenticate, so in a chain ["tokens", "web"] an invalid API token falls back to the session. That contradicts the docstring and the CHANGELOG. The check also reads only Authorization: Bearer, but TokenGuard.header can be configured. Fix: ask the member whether it saw a credential, e.g. an InvalidTokenException from a member is final while an AuthenticationException("Not authenticated.") lets the chain continue. Add a test for a token-driver chain.

Non-blocking

3. ChainGuard.user_from_token gives the same string to every member, so a session guard looks up a bearer string as a session id. Nothing in the package calls it today, but manager.guard("auth.api").user_from_token(x) would accept a raw session id as a bearer token. Either limit it to the token members or raise.
4. CHANGELOG.md: the class-level Auth.guard() change is listed under "Added". If it stays breaking, move it to "Breaking changes and upgrade notes" and use feat!. With fix 1 it would no longer be breaking.

Do not merge. The app PR Salut-Keera/salut-keera-ai#725 pins this head SHA, so it must be re-pinned after these fixes.

[claude-tmgbedu]

Re-review: APPROVED

Head reviewed: 657fec782f3ebe1ae1a8a5a7f9e73a52a483c05a. Full suite: 441 passed, 92 skipped. ruff check . is clean.

Both earlier blockers are fixed:

1. Backward compatibility. Inside an active request, GuardDependency.__getattr__ forwards attribute access to context.manager.guard(self.name). Dunder names and name are excluded, so FastAPI's introspection and __eq__/__hash__ are not affected. Outside a request it raises a clear AttributeError. Both cases are tested. The CHANGELOG lists this under "Breaking changes and upgrade notes", with the remaining caveat (no identity or isinstance match) and a migration path.
2. The chain treats a presented token as final for every member type. presented_token(request) on TokenGuard/AsyncTokenGuard reads the configured header. oauth2 members fall back to Authorization: Bearer, and session members never count as reading a token. Tests cover the default header and X-Api-Token.

user_from_token now skips session members, and a chain of only session members raises InvalidTokenException. Both cases are tested.

Non-blocking, for later:

• In a chain with two members that both read Authorization (an oauth2 guard and a token guard), the first member's rejection is final, so the second never gets the token. This is consistent with the documented rule. It may be worth stating in the README if someone builds an "OAuth or personal token" chain.
• __getattr__ calls manager.guard(name). If the name is not configured, attribute lookups inside a request raise the manager's error rather than AttributeError. That only happens on a misconfiguration.

Not merged; that is left to the PM.