Metadata-Version: 2.5
Name: mintid-agent
Version: 0.2.0
Summary: MintID agent client: agent credential custody, witness refresh and the x402 payment-identity loop over the MintID holder library
Project-URL: Homepage, https://mintid.net
Project-URL: Documentation, https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/15-agent-clients.md
Project-URL: Repository, https://gitlab.com/mintid/mintid
Project-URL: Source, https://gitlab.com/mintid/sdk-python
Project-URL: Issues, https://gitlab.com/mintid/mintid/-/issues
Project-URL: Security, https://gitlab.com/mintid/mintid/-/blob/main/SECURITY.md
Author-email: Marc Molas <marc@mintid.net>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,identity,mintid,verifiable-credentials,web-bot-auth,x402,zero-knowledge
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: mintid-proof-core<0.5,>=0.4.0
Provides-Extra: ed25519
Requires-Dist: cryptography>=42; extra == 'ed25519'
Description-Content-Type: text/markdown

# mintid-agent

The MintID agent client for Python: the agent runtime's side of an agent
credential. An agent credential proves that a person, verified at an issuer,
delegated *this* agent to pay *this* kind of counterparty within stated
bounds, and nothing about who that person is. The client obtains the
credential from an agent offer, keeps its witnesses current, answers a
seller's identity requirement inside an x402 payment flow, and refuses,
before anything is sent or paid, whatever the delegation does not cover.

It carries no cryptography of its own: proofs come from the MintID holder
library (`mintid-proof-core`), signatures from a signer you inject.

## Where it fits

MintID is a network for verifiable, human-backed identity. Accepted issuers
verify people and issue the credentials; the chain publishes their status
roots, their bonds and the registries; each verifier decides on its own
service. MintID itself issues nothing, certifies nothing and verifies nobody.

The agent client runs in your own infrastructure, and its keys never leave
it: the credential's private bytes go only to the credential store you inject
(encryption at rest is yours), and the request-signing key stays behind the
signer you inject. The operator who mints the agent, not the agent, decides
the delegation.

## Install

```bash
pip install mintid-agent              # Python 3.12 or later
pip install "mintid-agent[ed25519]"   # with the software Ed25519 signer
```

It depends on `mintid-proof-core`, which compiles the Rust proof core in;
where no wheel matches your platform, pip builds it from source with a Rust
toolchain. Version 0.2.0 (with `mintid-proof-core` 0.4), published from the
main repository, https://gitlab.com/mintid/mintid (`sdk/python/mintid-agent`).

**Upgrading from 0.1.** Two behaviour changes. The holder checks every
challenge's signature before it presents: give `AgentClient` a source of
verifiers' request keys, `verifiers=` (`ProvenVerifierKeys` over a proven
chain read, or `StaticVerifierKeys` of records you pinned); without one, or
for an unsigned or wrongly signed challenge, `present` raises
`ChallengeRefused` and nothing is sent or paid. And `refresh().usable` is
true only once a finalised root anchors every scope value of the delegation
(`agent.scope_anchored`), so a new agent no longer presents into
`scope_axis_unprovable`: poll `refresh()` until `usable`, as below.

## Example

```python
import time

from mintid_agent import AgentClient
from proof_core.holder import urllib_transport

# offer: the agent offer the operator made; principal: the principal's
# identity credential (a proof_core.holder.Holder); store: your CredentialStore.
# verifiers: where the holder reads verifiers' request keys (ProvenVerifierKeys
# over a proven chain read, or StaticVerifierKeys of records you pinned).
agent = AgentClient.issue_from_offer(
    offer, principal, transport=urllib_transport(), store=store, verifiers=verifiers
)

while not agent.refresh().usable:      # the status witness, then the scope log;
    time.sleep(5)                      # usable once a root anchors the delegation
envelope = agent.present(challenge)    # checks the verifier's signature (ChallengeRefused), then
                                       # proves or refuses, naming what the delegation cannot satisfy
result = agent.pay(url, payer=payer)   # one paid request; your payer builds the payment header
```

The same client renews the credential from a renewal offer and holds the
agent's kill switch: holder self-revocation, submitted through a privacy
relay and confirmed against the chain.

## Where to test

On the public testnet and its KYC sandbox, and only there: check the status
line of [its page](https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/17-sandbox-and-testnet.md)
first. Nothing minted on it carries weight. The single-node production chain
is not for third parties and is never a place to test.

## Links

- Documentation: https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/15-agent-clients.md
- Source: https://gitlab.com/mintid/mintid (`sdk/python/mintid-agent`), where
  issues and merge requests go; read-only mirror: https://gitlab.com/mintid/sdk-python
- Public testnet: https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/17-sandbox-and-testnet.md
- Security: report a vulnerability privately to security@mintid.net, never in
  a public issue; policy: https://gitlab.com/mintid/mintid/-/blob/main/SECURITY.md
- Website: https://mintid.net

## Licence

Apache License 2.0 (`LICENSE`, `NOTICE`). Author: Marc Molas.

---

## This repository

This is a read-only mirror of `sdk/python/mintid-agent` of the MintID source tree,
https://gitlab.com/mintid/mintid, and is published from it: each publication replaces its
content, and nothing is merged here. Issues and merge requests go to the main
project, https://gitlab.com/mintid/mintid/-/issues; a vulnerability goes privately to the
address in its SECURITY.md, never to a public issue. Licence: Apache License
2.0 (LICENSE and NOTICE); contributions follow the main project's
CONTRIBUTING.md.

Package: `mintid-agent` (Python >= 3.12). It depends on `mintid-proof-core`,
the Python bindings of the Rust proof core and holder library, whose source is
`identity-proof-core/python` of the main repository. To work here against the
proof core of the same revision, build it from a clone of the main repository
(`pip install ./identity-proof-core/python`, with a Rust toolchain), then
install this package (`pip install -e ".[ed25519]"`).

<!-- Published from source revision e52564fc4f58. -->
