# Contributing to a2a-passport

Thanks for considering a contribution. This project is young and the
places it needs help are pretty concrete:

## High-value areas

- **Real-account validation for the cloud integrations.** `cognito_verifier`,
  `entra_id_verifier`, and the GCP ID token provider/verifier
  (`integrations/aws.py`, `azure.py`, `gcp.py`) are only unit-tested against
  mocked boto3/azure-identity/google-auth calls so far. Running any of them
  against a real Cognito user pool, Entra ID tenant, or GCP service account
  and reporting back (or contributing the test) is high value. Same goes
  for `JWKSVerifier` generically against Auth0/Keycloak/Okta.
- **Persistent task stores.** An example wiring a database-backed
  `TaskStore` (a2a-sdk ships one as an extra) into `build_agent_app`.
- **Agent registry/discovery.** Replacing hardcoded agent URLs with a
  lookup service is the biggest open design question in this project --
  open an issue to discuss the approach before sending a large PR.
- **Streaming (SSE) support.** Currently explicitly out of scope; there's a
  known Starlette `BaseHTTPMiddleware`-vs-SSE-buffering interaction to work
  around.

## Development setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev,otel,aws,azure,gcp]"
pytest tests/ -v
ruff check src/ tests/ examples/
mypy src/
```

## Guidelines

- Every new feature needs a test that fails without the change.
- Keep the `TokenProvider`/`TokenVerifier` protocols the only extension
  point for auth -- if you need to add a knob, prefer a new implementation
  of one of these over adding branches to existing classes.
- Don't add a hard dependency on any single IdP's SDK to the core package;
  IdP-specific code belongs in an example or an optional extra.
- Run `ruff format` before submitting; CI will reject unformatted code.

## Reporting bugs / requesting features

Open a GitHub issue. For security vulnerabilities, see
[SECURITY.md](SECURITY.md) instead -- do not open a public issue.
