Metadata-Version: 2.4
Name: algovoi-passport-sdk
Version: 0.1.1
Summary: Build passport-aware agents: present an AlgoVoi Agent Passport on outbound x402/A2A calls, and guard your relying-party agent by verifying incoming passports offline with a policy of scopes, spend floor, and allowed agents.
Author-email: AlgoVoi <chopmob@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://docs.algovoi.co.uk/payment-rails-sqlite
Project-URL: AlgoVoi Payment Rails, https://docs.algovoi.co.uk/payment-rails-sqlite
Project-URL: Source, https://github.com/chopmob-cloud/algovoi-passport-sdk
Keywords: agent,passport,x402,a2a,falcon,pqc,authorization,guard,sdk
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: algovoi-passport-client>=0.1.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Dynamic: license-file

# algovoi-passport-sdk

A small SDK for building **passport-aware agents** on the AlgoVoi payment rails. It turns
the two agent patterns into a few lines each: an agent that **presents** its Agent Passport
on outbound calls, and a relying-party agent that **guards** its endpoints by verifying
presented passports offline and enforcing a policy.

Built on [`algovoi-passport-client`](https://github.com/chopmob-cloud/algovoi-passport-client).
Part of the [AlgoVoi Payment Rails](https://docs.algovoi.co.uk/payment-rails-sqlite).

```bash
pip install algovoi-passport-sdk
```

## Present your passport (agent side)

```python
from algovoi_passport_sdk import PassportHolder

me = PassportHolder.from_env()            # $ALGOVOI_AGENT_PASSPORT, or from_file(path)

# attach it to an outbound call
headers  = me.apply({"Accept": "application/json"})   # adds X-Agent-Passport
metadata = me.a2a_metadata()                           # A2A message metadata
```

## Guard your agent (relying-party side)

```python
from algovoi_passport_sdk import PassportGuard, PassportPolicy

guard = PassportGuard(
    issuer_url="https://pay.issuer.com",              # resolves + caches key & CRL
    policy=PassportPolicy(required_scopes=("pay:invoice",), min_spend_microusd=1_000_000),
)

decision = guard.check(incoming_headers, required_scope="pay:invoice")
if decision:                                          # truthy only when admitted
    verdict = decision.verdict                        # agent_did, scopes, spend, ...
    ...                                               # grant the spend
else:
    reject(decision.reason)                           # e.g. "revoked: REVOKED"
```

`guard.check(...)` accepts a raw credential, an x402 headers mapping, an A2A metadata
mapping, or a full A2A message; it pulls the passport out, verifies it **offline**
(fail-closed), and applies the policy. Issuer key and revocation list are cached with a TTL
(default 300s). For a strictly offline trust base, pin them instead of fetching:

```python
guard = PassportGuard(issuer_keys={kid: pk_bytes}, crl={"revoked": [...]})
```

### Policy

`PassportPolicy` fields, all optional:

- `required_scopes`: every scope must be present on the passport.
- `min_spend_microusd`: a floor; the passport's own limit must cover it (a passport with
  no stated limit is treated as unbounded).
- `allowed_agents`: an allowlist of `agent_did`s.
- `require_revocation_check`: default True; if the CRL cannot be confirmed the passport is
  denied as `unverifiable`, never admitted.

Per-call `required_scope` and `min_spend` on `check(...)` add to the policy.

## FastAPI

```python
from fastapi import FastAPI, Depends
from algovoi_passport_sdk import PassportGuard
from algovoi_passport_sdk.integrations import fastapi_passport_dependency

guard = PassportGuard(issuer_url="https://pay.issuer.com")
require_pay = fastapi_passport_dependency(guard, scope="pay:invoice")

app = FastAPI()

@app.post("/charge")
def charge(verdict = Depends(require_pay)):   # 403 unless a valid, in-scope passport is presented
    return {"agent": verdict.agent_did}
```

Install the extra with `pip install 'algovoi-passport-sdk[fastapi]'`.

## License

Apache-2.0. (c) AlgoVoi. Keep the NOTICE attribution when you redistribute.
