Plug middleware for A2A agent authentication.

Extracts credentials from incoming requests based on configured security schemes and delegates validation to a user-supplied verify callback. On success, the verified identity is stored in conn.private[:a2a][:auth] where A2A.Plug can forward it to the agent as context.metadata["a2a.auth"].

Usage

# In a Phoenix pipeline or plug pipeline, before A2A.Plug:
plug A2A.Plug.Auth,
  schemes: %{
    "bearer_auth" => %A2A.SecurityScheme.HTTPAuth{scheme: "bearer"}
  },
  verify: &MyApp.Auth.verify_a2a/3

forward "/a2a", A2A.Plug, agent: MyAgent, base_url: "..."

Options

• :schemes — %{String.t() => SecurityScheme.t()} mapping scheme names to their definitions (required)

• :verify — (scheme_name, credential, conn) -> {:ok, identity} | {:error, reason} callback for credential validation (required)

• :security — [%{String.t() => [String.t()]}] list of security requirement alternatives. Each map requires all its schemes (AND); the first fully-satisfied alternative wins (OR). Defaults to each scheme as an independent alternative.
• :exempt_paths — list of path_info lists that bypass authentication (default: [[".well-known", "agent-card.json"]])
• :realm — realm string for WWW-Authenticate headers (default: "a2a")

Verify Callback

The callback receives the scheme name, extracted credential, and conn:

def verify(scheme_name, credential, conn)

Where credential is:

• String.t() for Bearer tokens, API keys, OAuth2, OpenID Connect
• {username, password} for HTTP Basic auth

Must return {:ok, identity_map} or {:error, reason_string}.