human-attestation
Official HAP (Human Attestation Protocol) SDK for Python.
HAP is an open standard for verified human effort. It enables Verification Authorities (VAs) to cryptographically attest that a sender took deliberate, costly action when communicating with a recipient.
Installation
pip install human-attestation
Quick Start
Verifying a Claim (For Recipients)
import asyncio
from human_attestation import verify_claim, is_claim_expired, is_claim_for_recipient
async def main():
# Verify a claim from a HAP ID
claim = await verify_claim("hap_abc123xyz456", "ballista.jobs")
if claim:
# Check if not expired
if is_claim_expired(claim):
print("Claim has expired")
return
# Verify it's for your organization
if not is_claim_for_recipient(claim, "yourcompany.com"):
print("Claim is for a different recipient")
return
print(f"Verified {claim['method']} application to {claim['to']['name']}")
asyncio.run(main())
Verifying from a URL
from human_attestation import extract_id_from_url, verify_claim
async def verify_from_url(url: str):
# Extract HAP ID from a verification URL
hap_id = extract_id_from_url(url)
if hap_id:
claim = await verify_claim(hap_id, "ballista.jobs")
return claim
return None
Verifying Signature Manually
from human_attestation import fetch_claim, verify_signature
async def verify_with_signature(hap_id: str):
# Fetch the claim
response = await fetch_claim(hap_id, "ballista.jobs")
if response.get("valid") and "jws" in response:
# Verify the cryptographic signature
result = await verify_signature(response["jws"], "ballista.jobs")
if result["valid"]:
print("Signature verified!", result["claim"])
else:
print("Signature invalid:", result["error"])
Signing Claims (For Verification Authorities)
import json
from human_attestation import (
generate_key_pair,
export_public_key_jwk,
create_claim,
sign_claim,
)
# Generate a key pair (do this once, store securely)
private_key, public_key = generate_key_pair()
# Export public key for /.well-known/hap.json
jwk = export_public_key_jwk(public_key, "my_key_001")
well_known = {"issuer": "my-va.com", "keys": [jwk]}
print(json.dumps(well_known, indent=2))
# Create and sign a claim
claim = create_claim(
method="physical_mail",
description="Priority mail packet with handwritten cover letter",
recipient_name="Acme Corp",
domain="acme.com",
issuer="my-va.com",
expires_in_days=730, # 2 years
cost={"amount": 1500, "currency": "USD"},
time=1800,
physical=True,
)
jws = sign_claim(claim, private_key, kid="my_key_001")
print("Signed JWS:", jws)
API Reference
Verification Functions
| Function | Description |
|---|---|
verify_claim(hap_id, issuer) |
Fetch and verify a claim, returns claim or None |
fetch_claim(hap_id, issuer) |
Fetch raw verification response from VA |
verify_signature(jws, issuer) |
Verify JWS signature against VA's public keys |
fetch_public_keys(issuer) |
Fetch VA's public keys from well-known endpoint |
is_valid_id(id) |
Check if string matches HAP ID format |
extract_id_from_url(url) |
Extract HAP ID from verification URL |
is_claim_expired(claim) |
Check if claim has passed expiration |
is_claim_for_recipient(claim, domain) |
Check if claim targets specific recipient |
Signing Functions (For VAs)
| Function | Description |
|---|---|
generate_key_pair() |
Generate Ed25519 key pair |
export_public_key_jwk(key, kid) |
Export public key as JWK |
sign_claim(claim, private_key, kid) |
Sign a claim, returns JWS |
generate_id() |
Generate cryptographically secure HAP ID |
create_claim(...) |
Create claim with defaults |
Types
from human_attestation import (
Claim,
ClaimCost,
ClaimTarget,
VerificationResponse,
WellKnown,
Jwk,
)
Requirements
- Python 3.9+
- httpx (for async HTTP)
- PyJWT with cryptography
License
Apache-2.0
Metadata
Release files for human-attestation 0.4.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| human_attestation-0.4.4.tar.gz | 9.7 kB | Without provenance | Details for human_attestation-0.4.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| human_attestation-0.4.4-py3-none-any.whl | Python 3 | none | any | Details for human_attestation-0.4.4-py3-none-any.whl |
Total release size: 22.3 kB
Release files / human_attestation-0.4.4.tar.gz
| Download URL | human_attestation-0.4.4.tar.gz |
|---|---|
| Size | 9.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7086c170770a9e6ac7fa938454a4f5156675b203aed4f13cf34b5f974ec66a42
|
|
BLAKE2b-256 checksum How to use checksums |
44ad6cd90e94a130975f3c42726663d3dcd8fc6c188c96f6d1e2f92368bf5d90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Release files / human_attestation-0.4.4-py3-none-any.whl
| Download URL | human_attestation-0.4.4-py3-none-any.whl |
|---|---|
| Size | 12.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98554d7b91b93bcb43a9c6d470f8656faffeee3dbef98a5f3091b4bfa8ccea33
|
|
BLAKE2b-256 checksum How to use checksums |
3b614577088da123e3455363853b827854972a3337ecb85b03af2211463b60cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Security for human-attestation 0.4.4
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.