feat(framework): Add AppIo auth interceptors

[msheller]

Issue

SuperExecs and *Apps can impersonate each other when calling *AppIo RPCs.

Proposal

Part 1 of 5 PRs.

Full set proposal:
Using gRPC intercetors:

• Add token passing/verification to all *AppIo RPCs callable by *Apps
• Add signed metadata and verification to all *AppIo RPCs callable by SuperExecs
• Where callable by both, support both (with proper enforcement re: identity of caller).

This PR is 1 of 5 planned PRs:

1. Introduce the interceptors, auth abstraction and token mechanism
2. Apply them to ServerAppIoServicer.
3. Apply them to ClientAppIoServicer.
4. Apply them to SimulationIoServicer.
5. Add SuperExec signed metadata mechanism (abstraction should enable cleanly adding to all servicers in one PR).

Explanation

Created a light-weight auth abstraction intended to simplify the next set of PRs. See internal RFC for abstraction details.

The mental model is:

• Transport layer = parsing + plumbing
• Auth layer = policy + verification + identity
• Servicer layer = business logic with authenticated identity

This PR introduces the interceptor transport layer, the auth layer and the token mechanism. It does NOT touch servicers. I chose to include these three in the same PR because:

1. I think it helps ground the abstraction to see these specific instantiations, since the abstraction is the new concept.
2. I am hoping that PRs 2-5 will only depend on this PR1, simplifying our async work (e.g. reviews gating further implementation).

Checklist

• Implement proposed change
• Write tests
• Update documentation
• Make CI checks pass
• Ping maintainers on Slack (channel #contributions)

Any other comments?

NOTE: this solution version conflates authentication-mechanism policy with authorization policy: SuperExecs and *Apps are distinguished by authentication mechanism (token vs. signed metadata). While I believe this is okay for now, we should separate these concerns as soon as we add authorization complexity, or if we ever decide to support multiple mechanisms for a given process (i.e. if *Apps can use tokens or signed metadata).

Codex gave me this nice summary:

Summary

This PR introduces the AppIo authentication foundation and interceptor framework, without wiring it into specific services yet.

What’s included

• Added a transport-agnostic auth core in framework/py/flwr/supercore/auth/:

  • AuthInput, SignedMetadataAuthInput, CallerIdentity
  • Authenticator protocol
  • AuthDecisionEngine
  • MethodAuthPolicy and policy-map validation helpers
  • Shared auth constants and exports

• Added general AppIo interceptors in framework/py/flwr/supercore/interceptors/:

  • Server interceptor for centralized auth enforcement
  • Client interceptor for token metadata injection
  • Context helper accessors (get_authenticated_*)
  • Run-binding helper (verify_authenticated_run_matches_request_run_id)
  • Canonical auth-deny response behavior
  • Fail-closed behavior for unknown methods

• Added test coverage for both layers:

  • framework/py/flwr/supercore/auth/appio_auth_test.py
  • framework/py/flwr/supercore/interceptors/appio_auth_interceptor_test.py

Hardening and cleanup

• Removed dead/unused auth context state.
• Ensured token context is exposed only when token auth is the successful mechanism.
• Added mechanism checks in token-only helper paths.
• Refined signed-metadata presence semantics (absent vs present but malformed).
• Moved APP_TOKEN_HEADER from common/constant.py to supercore/auth/constant.py.

Scope boundary

• This PR is intentionally foundation-only:
  • No service wiring yet for ServerAppIo, ClientAppIo, or SimulationIo.
  • No SuperExec signed-metadata verification logic yet (only abstraction support).

[Copilot]

Pull request overview

Introduces the first part of an AppIo authentication framework by adding transport-level gRPC interceptors plus a transport-agnostic auth/policy abstraction, enabling upcoming PRs to apply consistent authentication enforcement across AppIo servicers.

Changes:

• Add AppIo gRPC client/server interceptors for token and (future) signed-metadata auth inputs.
• Introduce transport-agnostic auth primitives (decision engine, authenticators, policies) and signed-metadata header constants.
• Add unit tests covering token auth flows, signed-metadata extraction/presence semantics, and policy validation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
framework/py/flwr/supercore/interceptors/appio_auth_interceptor_test.py	Adds interceptor-focused tests for token handling, denial behavior, and signed-metadata extraction.
framework/py/flwr/supercore/interceptors/appio_auth_interceptor.py	Implements AppIo client/server interceptors plus helper accessors for authenticated context.
framework/py/flwr/supercore/interceptors/init.py	Exposes interceptor APIs from the interceptors package.
framework/py/flwr/supercore/auth/policy.py	Adds MethodAuthPolicy and strict policy-table validation helper.
framework/py/flwr/supercore/auth/constant.py	Defines auth mechanism identifiers and signed-metadata header keys.
framework/py/flwr/supercore/auth/appio_auth_test.py	Adds unit tests for decision engine behavior, token authenticator, and policy validation.
framework/py/flwr/supercore/auth/appio_auth.py	Implements the core auth abstractions (AuthInput, decision engine, token authenticator).
framework/py/flwr/supercore/auth/init.py	Exposes auth primitives/constants as a package API.
framework/py/flwr/common/constant.py	Adds the APP_TOKEN_HEADER constant for AppIo token metadata.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.