Skip to main content

agent-warrant

A portable, cryptographically-verifiable authority grant for AI agents — cross-org, no shared infrastructure.

Lets one team's AI agent cryptographically verify another team's agent's delegated authority, with no shared secret. Ships two IssuerResolver implementations: out-of-band issuer-key pinning via PinnedResolver (TOFU), and real trust bootstrap via DidWebResolver (HTTPS + domain ownership, per the did:web method spec). Also ships opt-in revocation checking (RevocationChecker) — pre-expiry invalidation of a specific Grant, checked as the last gate in verify(). Spun out of agent-guard (which stays the local, single-org authorization/audit boundary) specifically because cross-org verification needs a different crypto trust model — asymmetric signing, not a shared HMAC secret.

Deeper reference: docs/DESIGN.md (why it's shaped this way, including the design history — what was tried, what was corrected, and why), docs/THREAT_MODEL.md (what's defended, what's explicitly not).

The shape

  • A Grant is issuer-signed (Ed25519), scoped, expiring — VC-data-model-shaped, not VC-spec-conformant (no credentialStatus field on the Grant itself; see THREAT_MODEL.md). Revocation checking exists, but as a separate, opt-in gate verify() runs against a caller-supplied RevocationChecker — not as data carried on the credential.
  • subject is the holder's public key — but a Grant alone is still a bearer credential unless paired with a fresh PossessionProof at verification time, proving the presenter actually holds the matching private key.
  • IssuerResolver resolves an issuer identifier to a public key. PinnedResolver — honestly named: it performs zero trust verification, it's out-of-band key pinning (TOFU). DidWebResolver is real trust bootstrap via HTTPS + domain ownership: it fetches https://<domain>/.well-known/did.json (or a path-scoped variant, e.g. example.com:agents:team-a → https://example.com/agents/team-a/did.json) and extracts an Ed25519 key from the DID document — binding selection to the document's id, the method's controller, and any declared assertionMethod, not array order. Every failure (DNS/HTTP error, non-200 status, id mismatch, malformed document, wrong key type, ambiguous or no matching verificationMethod) fails closed as UnresolvableIssuer.
  • Revocation is opt-in: a Verifier constructed without a revocation_checker behaves exactly as before this existed — TTL is the only expiry mechanism. Opting in means the issuer publishes a RevocationList (a signed set of revoked grant_binding values carrying a signed issued_at/expires_at/monotonic sequence — see sign_revocation_list()), and a caller wires up StaticRevocationChecker (for an already-fetched list) or HttpRevocationChecker (fetches + verifies on every is_revoked() call, no caching). Any inability to determine revocation status — fetch failure, malformed list, bad signature, a stale/expired or rolled-back list, or a list whose issuer doesn't match the grant's — fails closed: the grant is rejected, never silently treated as "not revoked." StaticRevocationChecker checks freshness only when it is constructed and keeps answering from that list afterwards; replace it before the list's expires_at.

Install

pip install agent-warrant

Development

Dev dependencies (pytest, ruff, hypothesis) are the dev extra. Quote the extra so the shell does not expand the brackets:

uv venv
uv pip install -e '.[dev]'    # or, inside any venv: pip install -e '.[dev]'
.venv/bin/ruff check
.venv/bin/ruff format --check
.venv/bin/pytest -q

Quickstart

from agent_warrant import Issuer, HolderKeypair, PinnedResolver, Verifier, generate_keypair, encode_public_key

# Team A: mints a grant for a holder it doesn't need to share any secret with.
team_a_key = generate_keypair()
issuer = Issuer(issuer_id="team-a", private_key=team_a_key)

holder_key = generate_keypair()
holder = HolderKeypair(holder_key)
grant = issuer.issue(subject=encode_public_key(holder_key.public_key()), scope={"tool": "read_file"})
proof = holder.prove_possession(grant)

# Team B: only ever obtains team A's PUBLIC key, out-of-band. No shared secret.
# `path_prefix` is illustrative application data: agent-warrant authenticates
# the scope but does not interpret or enforce it for authorization.
resolver = PinnedResolver({"team-a": team_a_key.public_key()})
verifier = Verifier(resolver)

result = verifier.check(grant.encode(), proof)
assert result.valid

A stolen grant.encode() string alone is not enough — presenting it without a valid PossessionProof (or with a proof forged by a different keypair) is rejected. See tests/test_integration.py::test_stolen_grant_without_possession_proof_is_rejected for the live proof.

did:web, instead of pinning

from agent_warrant import DidWebResolver, Verifier

# No out-of-band key exchange -- team-a's key is fetched from
# https://team-a.example.com/.well-known/did.json and cryptographically
# tied to domain ownership over HTTPS, the same trust model TLS uses.
resolver = DidWebResolver()
verifier = Verifier(resolver)
result = verifier.check(grant.encode(), proof)  # grant.issuer == "team-a.example.com"

Revocation, opt-in

from agent_warrant import StaticRevocationChecker, Verifier, sign_revocation_list

# Team A decides to invalidate a specific grant before its TTL expires
# (compromised holder key, mistaken scope, ended sponsorship) and signs a
# RevocationList naming it -- by grant_binding, this project's stable
# identity for a specific Grant (see PossessionProof.grant_binding).
revocation_list = sign_revocation_list("team-a", [proof.grant_binding], team_a_key)

# Team B opts in by wiring a RevocationChecker into its Verifier. Without
# this, revocation is never checked -- default behavior is unchanged.
checker = StaticRevocationChecker(revocation_list, resolver)
verifier = Verifier(resolver, revocation_checker=checker)
result = verifier.check(grant.encode(), proof)
assert result.valid is False and "revoked" in result.reason

HttpRevocationChecker + HttpRevocationListFetcher do the same thing over HTTPS instead of an in-process RevocationList -- fetching and re-verifying the signed list on every is_revoked() call, no caching. If the revocation endpoint is unreachable, verification fails closed (rejected), not open.

Constraints worth knowing before you hit them

  • Encoded grant size: capped at agent_warrant.grant.MAX_ENCODED_GRANT_BYTES (16KB). A compact authority claim never legitimately needs more — if your scope is large enough to hit this, reconsider what you're encoding into it rather than raising the constant (it's load-bearing for a resource-exhaustion defense, see docs/THREAT_MODEL.md).
  • DidWebResolver fetches on every resolve() call, no caching. And because grant.issuer reaches resolver.resolve() before any signature check, an unauthenticated grant can make the verifying process issue an outbound HTTPS request to an attacker-influenced host. https_fetch.py resolves the host once, rejects the fetch if any resolved address is private/loopback/link-local/reserved/multicast/unspecified, pins the screened IP, and connects to it directly while verifying TLS against the original hostname (SSRF hardening; this closes the DNS-rebinding TOCTOU a check-then-connect pattern would have). A wall-clock watchdog bounds the total time any single fetch can consume against a slow-drip host. See docs/THREAT_MODEL.md for the remaining residual (the DNS-resolution step uses the OS resolver's own timeout).
  • Revocation is opt-in and unbundled from StatusList2021. It's a small signed set of revoked grant_binding values, sized for a known, bounded cross-org verifier population -- not the anonymity-preserving bitstring StatusList2021 uses for public, anonymous-verifier scale. See docs/DESIGN.md for why that tradeoff fits this project's actual shape.

Design history worth knowing before extending this

This design went through two real review cycles (documented in full at ~/identity-unification-plan.md in the originating session) before any code was written. The most important correction: an earlier draft called subject = holder's public key alone "holder-binding" — it wasn't. A public key sitting in an issuer-signed credential with no separate possession check at verification time is still a bearer credential; anyone who intercepts the encoded grant can replay it. PossessionProof exists specifically to close that gap, mirroring agent-guard's own PoPProof/verify_pop pattern. Read docs/DESIGN.md before changing anything in grant.py's verify() — most of its structure (narrow exception catches, version-check-first ordering, the iat type guard) is there because a specific finding required it, not by convention.

Metadata

Release files for agent-warrant 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-warrant 0.2.0
File Size Uploaded Provenance Actions
agent_warrant-0.2.0.tar.gz 107.6 kB With provenance Details for agent_warrant-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-warrant 0.2.0
File Interpreter ABI Platform Actions
agent_warrant-0.2.0-py3-none-any.whl Python 3 none any Details for agent_warrant-0.2.0-py3-none-any.whl

Total release size: 165.7 kB

Release files / agent_warrant-0.2.0.tar.gz

Download URL agent_warrant-0.2.0.tar.gz
Size 107.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f74ad7959694eaa0b2715989f05210790fc331aa830fed0aeb781b25efdacf1e
BLAKE2b-256 checksum
How to use checksums
7cd5b32221c3061736048e8ab5d9bcfbdecc7297f9747a87a602c1dc5bbf83f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / agent_warrant-0.2.0-py3-none-any.whl

Download URL agent_warrant-0.2.0-py3-none-any.whl
Size 58.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88781d900121dd6e5fb79c8473f1580bdb8a5423287b571ca795a414f9b201df
BLAKE2b-256 checksum
How to use checksums
fff0b5b885cd7291e6b821eabb9e52e605603fb3b7dce1f0005038f7b425a40d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for agent-warrant 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_warrant-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page