human-attestation 0.3.6__tar.gz

human_attestation-0.3.6/.gitignore

@@ -0,0 +1,32 @@
+# OS
+.DS_Store
+
+# AI assistant files
+CLAUDE.md
+
+# Dependencies
+node_modules/
+vendor/
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Build outputs
+dist/
+build/
+target/
+bin/
+obj/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Package manager locks (keep in individual SDK dirs)
+# But ignore at root
+/package-lock.json
+/yarn.lock
+.claude/

human_attestation-0.3.6/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: human-attestation
+Version: 0.3.6
+Summary: Official SDK for HAP (Human Attestation Protocol) - cryptographic proof of verified human effort
+Project-URL: Homepage, https://github.com/Blue-Scroll/hap
+Project-URL: Repository, https://github.com/Blue-Scroll/hap.git
+Project-URL: Documentation, https://github.com/Blue-Scroll/hap#readme
+Author: BlueScroll Inc.
+License-Expression: Apache-2.0
+Keywords: attestation,cryptographic,ed25519,hap,human-attestation-protocol,jws,proof-of-effort,sender-verification,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install human-attestation
+```
+
+## Quick Start
+
+### Verifying a Claim (For Recipients)
+
+```python
+import asyncio
+from hap import verify_hap_claim, is_claim_expired, is_claim_for_recipient
+
+async def main():
+    # Verify a claim from a HAP ID
+    claim = await verify_hap_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
+
+```python
+from hap import extract_hap_id_from_url, verify_hap_claim
+
+async def verify_from_url(url: str):
+    # Extract HAP ID from a verification URL
+    hap_id = extract_hap_id_from_url(url)
+
+    if hap_id:
+        claim = await verify_hap_claim(hap_id, "ballista.jobs")
+        return claim
+    return None
+```
+
+### Verifying Signature Manually
+
+```python
+from hap 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)
+
+```python
+import json
+from hap import (
+    generate_key_pair,
+    export_public_key_jwk,
+    create_human_effort_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_human_effort_claim(
+    method="physical_mail",
+    recipient_name="Acme Corp",
+    domain="acme.com",
+    tier="standard",
+    issuer="my-va.com",
+    expires_in_days=730,  # 2 years
+)
+
+jws = sign_claim(claim, private_key, kid="my_key_001")
+print("Signed JWS:", jws)
+```
+
+### Creating Recipient Commitment Claims
+
+```python
+from hap import create_recipient_commitment_claim, sign_claim
+
+claim = create_recipient_commitment_claim(
+    recipient_name="Acme Corp",
+    recipient_domain="acme.com",
+    commitment="review_verified",
+    issuer="my-va.com",
+    expires_in_days=365,
+)
+
+jws = sign_claim(claim, private_key, kid="my_key_001")
+```
+
+## API Reference
+
+### Verification Functions
+
+| Function                              | Description                                     |
+| ------------------------------------- | ----------------------------------------------- |
+| `verify_hap_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_hap_id(id)`                 | Check if string matches HAP ID format           |
+| `extract_hap_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_hap_id()`                     | Generate cryptographically secure HAP ID |
+| `create_human_effort_claim(...)`        | Create human_effort claim with defaults  |
+| `create_recipient_commitment_claim(...)` | Create recipient_commitment claim         |
+
+### Types
+
+```python
+from hap import (
+    HapClaim,
+    HumanEffortClaim,
+    RecipientCommitmentClaim,
+    VerificationResponse,
+    HapWellKnown,
+    HapJwk,
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx (for async HTTP)
+- PyJWT with cryptography
+
+## License
+
+Apache-2.0

human_attestation-0.3.6/README.md

@@ -0,0 +1,171 @@
+# 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
+
+```bash
+pip install human-attestation
+```
+
+## Quick Start
+
+### Verifying a Claim (For Recipients)
+
+```python
+import asyncio
+from hap import verify_hap_claim, is_claim_expired, is_claim_for_recipient
+
+async def main():
+    # Verify a claim from a HAP ID
+    claim = await verify_hap_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
+
+```python
+from hap import extract_hap_id_from_url, verify_hap_claim
+
+async def verify_from_url(url: str):
+    # Extract HAP ID from a verification URL
+    hap_id = extract_hap_id_from_url(url)
+
+    if hap_id:
+        claim = await verify_hap_claim(hap_id, "ballista.jobs")
+        return claim
+    return None
+```
+
+### Verifying Signature Manually
+
+```python
+from hap 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)
+
+```python
+import json
+from hap import (
+    generate_key_pair,
+    export_public_key_jwk,
+    create_human_effort_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_human_effort_claim(
+    method="physical_mail",
+    recipient_name="Acme Corp",
+    domain="acme.com",
+    tier="standard",
+    issuer="my-va.com",
+    expires_in_days=730,  # 2 years
+)
+
+jws = sign_claim(claim, private_key, kid="my_key_001")
+print("Signed JWS:", jws)
+```
+
+### Creating Recipient Commitment Claims
+
+```python
+from hap import create_recipient_commitment_claim, sign_claim
+
+claim = create_recipient_commitment_claim(
+    recipient_name="Acme Corp",
+    recipient_domain="acme.com",
+    commitment="review_verified",
+    issuer="my-va.com",
+    expires_in_days=365,
+)
+
+jws = sign_claim(claim, private_key, kid="my_key_001")
+```
+
+## API Reference
+
+### Verification Functions
+
+| Function                              | Description                                     |
+| ------------------------------------- | ----------------------------------------------- |
+| `verify_hap_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_hap_id(id)`                 | Check if string matches HAP ID format           |
+| `extract_hap_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_hap_id()`                     | Generate cryptographically secure HAP ID |
+| `create_human_effort_claim(...)`        | Create human_effort claim with defaults  |
+| `create_recipient_commitment_claim(...)` | Create recipient_commitment claim         |
+
+### Types
+
+```python
+from hap import (
+    HapClaim,
+    HumanEffortClaim,
+    RecipientCommitmentClaim,
+    VerificationResponse,
+    HapWellKnown,
+    HapJwk,
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx (for async HTTP)
+- PyJWT with cryptography
+
+## License
+
+Apache-2.0

human_attestation-0.3.6/hap/__init__.py

@@ -0,0 +1,100 @@
+"""
+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.
+
+Example - Verifying a claim (for recipients):
+    >>> import asyncio
+    >>> from hap import verify_hap_claim, is_claim_expired
+    >>>
+    >>> async def main():
+    ...     claim = await verify_hap_claim("hap_abc123xyz456", "ballista.jobs")
+    ...     if claim and not is_claim_expired(claim):
+    ...         print(f"Verified application to {claim['to']['name']}")
+    >>>
+    >>> asyncio.run(main())
+
+Example - Signing a claim (for VAs):
+    >>> from hap import generate_key_pair, sign_claim, create_human_effort_claim
+    >>>
+    >>> private_key, public_key = generate_key_pair()
+    >>> claim = create_human_effort_claim(
+    ...     method="physical_mail",
+    ...     recipient_name="Acme Corp",
+    ...     domain="acme.com",
+    ...     issuer="my-va.com",
+    ... )
+    >>> jws = sign_claim(claim, private_key, kid="key_001")
+"""
+
+from hap.types import (
+    HAP_ID_REGEX,
+    HAP_VERSION,
+    ClaimType,
+    CommitmentLevel,
+    RecipientCommitmentClaim,
+    HapClaim,
+    HapJwk,
+    HapWellKnown,
+    HumanEffortClaim,
+    RevocationReason,
+    VerificationMethod,
+    VerificationResponse,
+)
+from hap.verify import (
+    extract_hap_id_from_url,
+    fetch_claim,
+    fetch_public_keys,
+    is_claim_expired,
+    is_claim_for_recipient,
+    is_valid_hap_id,
+    verify_hap_claim,
+    verify_signature,
+)
+from hap.sign import (
+    create_recipient_commitment_claim,
+    create_human_effort_claim,
+    export_public_key_jwk,
+    generate_hap_id,
+    generate_key_pair,
+    sign_claim,
+)
+
+__version__ = "0.3.6"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Constants
+    "HAP_ID_REGEX",
+    "HAP_VERSION",
+    # Types
+    "ClaimType",
+    "CommitmentLevel",
+    "RecipientCommitmentClaim",
+    "HapClaim",
+    "HapJwk",
+    "HapWellKnown",
+    "HumanEffortClaim",
+    "RevocationReason",
+    "VerificationMethod",
+    "VerificationResponse",
+    # Verification functions
+    "extract_hap_id_from_url",
+    "fetch_claim",
+    "fetch_public_keys",
+    "is_claim_expired",
+    "is_claim_for_recipient",
+    "is_valid_hap_id",
+    "verify_hap_claim",
+    "verify_signature",
+    # Signing functions
+    "create_recipient_commitment_claim",
+    "create_human_effort_claim",
+    "export_public_key_jwk",
+    "generate_hap_id",
+    "generate_key_pair",
+    "sign_claim",
+]

human_attestation-0.3.6/hap/sign.py

@@ -0,0 +1,186 @@
+"""
+HAP claim signing functions (for Verification Authorities)
+"""
+
+import base64
+import json
+import secrets
+import string
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from hap.types import HAP_VERSION, RecipientCommitmentClaim, HapClaim, HumanEffortClaim
+
+# Characters used for HAP ID generation
+HAP_ID_CHARS = string.ascii_letters + string.digits
+
+
+def generate_hap_id() -> str:
+    """
+    Generates a cryptographically secure random HAP ID.
+
+    Returns:
+        A HAP ID in the format hap_[a-zA-Z0-9]{12}
+    """
+    suffix = "".join(secrets.choice(HAP_ID_CHARS) for _ in range(12))
+    return f"hap_{suffix}"
+
+
+def generate_key_pair() -> tuple[Ed25519PrivateKey, Ed25519PublicKey]:
+    """
+    Generates a new Ed25519 key pair for signing HAP claims.
+
+    Returns:
+        Tuple of (private_key, public_key)
+    """
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+def export_public_key_jwk(public_key: Ed25519PublicKey, kid: str) -> dict[str, Any]:
+    """
+    Exports a public key to JWK format suitable for /.well-known/hap.json
+
+    Args:
+        public_key: The public key to export
+        kid: The key ID to assign
+
+    Returns:
+        JWK dict
+    """
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    # Get the raw public key bytes
+    raw_bytes = public_key.public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+    # Base64url encode without padding
+    x = base64.urlsafe_b64encode(raw_bytes).rstrip(b"=").decode("ascii")
+
+    return {
+        "kid": kid,
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": x,
+    }
+
+
+def sign_claim(claim: HapClaim, private_key: Ed25519PrivateKey, kid: str) -> str:
+    """
+    Signs a HAP claim with an Ed25519 private key.
+
+    Args:
+        claim: The claim to sign
+        private_key: The Ed25519 private key
+        kid: Key ID to include in JWS header
+
+    Returns:
+        JWS compact serialization string
+    """
+    # Ensure version is set
+    claim_with_version = {**claim, "v": claim.get("v", HAP_VERSION)}
+
+    # Sign using PyJWT
+    jws = jwt.encode(
+        claim_with_version,
+        private_key,
+        algorithm="EdDSA",
+        headers={"kid": kid},
+    )
+
+    return jws
+
+
+def create_human_effort_claim(
+    method: str,
+    recipient_name: str,
+    issuer: str,
+    domain: Optional[str] = None,
+    tier: Optional[str] = None,
+    expires_in_days: Optional[int] = None,
+) -> HumanEffortClaim:
+    """
+    Creates a complete human effort claim with all required fields.
+
+    Args:
+        method: Verification method (e.g., "physical_mail")
+        recipient_name: Recipient name
+        issuer: VA's domain
+        domain: Recipient domain (optional)
+        tier: Service tier (optional)
+        expires_in_days: Days until expiration (optional)
+
+    Returns:
+        A complete HumanEffortClaim dict
+    """
+    now = datetime.now(timezone.utc)
+
+    claim: HumanEffortClaim = {
+        "v": HAP_VERSION,
+        "id": generate_hap_id(),
+        "type": "human_effort",
+        "method": method,
+        "to": {"name": recipient_name},
+        "at": now.isoformat().replace("+00:00", "Z"),
+        "iss": issuer,
+    }
+
+    if domain:
+        claim["to"]["domain"] = domain
+
+    if tier:
+        claim["tier"] = tier
+
+    if expires_in_days:
+        exp = now + timedelta(days=expires_in_days)
+        claim["exp"] = exp.isoformat().replace("+00:00", "Z")
+
+    return claim
+
+
+def create_recipient_commitment_claim(
+    recipient_name: str,
+    commitment: str,
+    issuer: str,
+    recipient_domain: Optional[str] = None,
+    expires_in_days: Optional[int] = None,
+) -> RecipientCommitmentClaim:
+    """
+    Creates a complete recipient commitment claim with all required fields.
+
+    Args:
+        recipient_name: Recipient's name
+        commitment: Commitment level (e.g., "review_verified")
+        issuer: VA's domain
+        recipient_domain: Recipient's domain (optional)
+        expires_in_days: Days until expiration (optional)
+
+    Returns:
+        A complete RecipientCommitmentClaim dict
+    """
+    now = datetime.now(timezone.utc)
+
+    claim: RecipientCommitmentClaim = {
+        "v": HAP_VERSION,
+        "id": generate_hap_id(),
+        "type": "recipient_commitment",
+        "recipient": {"name": recipient_name},
+        "commitment": commitment,
+        "at": now.isoformat().replace("+00:00", "Z"),
+        "iss": issuer,
+    }
+
+    if recipient_domain:
+        claim["recipient"]["domain"] = recipient_domain
+
+    if expires_in_days:
+        exp = now + timedelta(days=expires_in_days)
+        claim["exp"] = exp.isoformat().replace("+00:00", "Z")
+
+    return claim

human_attestation-0.3.6/hap/types.py

@@ -0,0 +1,114 @@
+"""
+HAP (Human Attestation Protocol) type definitions for Python
+"""
+
+import re
+from typing import Literal, TypedDict, Union
+
+# Protocol version
+HAP_VERSION = "0.1"
+
+# HAP ID format: hap_ followed by 12 alphanumeric characters
+HAP_ID_REGEX = re.compile(r"^hap_[a-zA-Z0-9]{12}$")
+
+# Type aliases
+ClaimType = Literal["human_effort", "recipient_commitment"]
+VerificationMethod = Literal["physical_mail", "video_interview", "paid_assessment", "referral"]
+CommitmentLevel = Literal["review_verified", "prioritize_verified", "respond_verified"]
+RevocationReason = Literal["fraud", "error", "legal", "user_request"]
+
+
+class ClaimTarget(TypedDict, total=False):
+    """Target recipient information"""
+    name: str
+    domain: str
+
+
+class RecipientInfo(TypedDict, total=False):
+    """Recipient information for recipient_commitment claims"""
+    name: str
+    domain: str
+
+
+class HumanEffortClaim(TypedDict, total=False):
+    """Human effort verification claim"""
+    v: str
+    id: str
+    type: Literal["human_effort"]
+    method: str
+    tier: str
+    to: ClaimTarget
+    at: str
+    exp: str
+    iss: str
+
+
+class RecipientCommitmentClaim(TypedDict, total=False):
+    """Recipient commitment claim"""
+    v: str
+    id: str
+    type: Literal["recipient_commitment"]
+    recipient: RecipientInfo
+    commitment: str
+    at: str
+    exp: str
+    iss: str
+
+
+# Union of all claim types
+HapClaim = Union[HumanEffortClaim, RecipientCommitmentClaim]
+
+
+class HapJwk(TypedDict):
+    """JWK public key for Ed25519"""
+    kid: str
+    kty: Literal["OKP"]
+    crv: Literal["Ed25519"]
+    x: str
+
+
+class HapWellKnown(TypedDict):
+    """Response from /.well-known/hap.json"""
+    issuer: str
+    keys: list[HapJwk]
+
+
+class VerificationResponseValid(TypedDict):
+    """Successful verification response"""
+    valid: Literal[True]
+    id: str
+    claims: HapClaim
+    jws: str
+    issuer: str
+    verifyUrl: str
+
+
+class VerificationResponseRevoked(TypedDict):
+    """Revoked claim response"""
+    valid: Literal[False]
+    id: str
+    revoked: Literal[True]
+    revocationReason: RevocationReason
+    revokedAt: str
+    issuer: str
+
+
+class VerificationResponseNotFound(TypedDict):
+    """Not found response"""
+    valid: Literal[False]
+    error: Literal["not_found"]
+
+
+class VerificationResponseInvalidFormat(TypedDict):
+    """Invalid format response"""
+    valid: Literal[False]
+    error: Literal["invalid_format"]
+
+
+# Union of all verification response types
+VerificationResponse = Union[
+    VerificationResponseValid,
+    VerificationResponseRevoked,
+    VerificationResponseNotFound,
+    VerificationResponseInvalidFormat,
+]

human_attestation-0.3.6/hap/verify.py

@@ -0,0 +1,272 @@
+"""
+HAP claim verification functions
+"""
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+import httpx
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+from hap.types import (
+    HAP_ID_REGEX,
+    HapClaim,
+    HapJwk,
+    HapWellKnown,
+    VerificationResponse,
+)
+
+
+def is_valid_hap_id(hap_id: str) -> bool:
+    """
+    Validates a HAP ID format.
+
+    Args:
+        hap_id: The HAP ID to validate
+
+    Returns:
+        True if the ID matches the format hap_[a-zA-Z0-9]{12}
+    """
+    return bool(HAP_ID_REGEX.match(hap_id))
+
+
+async def fetch_public_keys(
+    issuer_domain: str,
+    timeout: float = 10.0,
+    client: Optional[httpx.AsyncClient] = None,
+) -> HapWellKnown:
+    """
+    Fetches the public keys from a VA's well-known endpoint.
+
+    Args:
+        issuer_domain: The VA's domain (e.g., "ballista.jobs")
+        timeout: Request timeout in seconds
+        client: Optional httpx client to use
+
+    Returns:
+        The VA's public key configuration
+    """
+    url = f"https://{issuer_domain}/.well-known/hap.json"
+
+    if client:
+        response = await client.get(url, timeout=timeout)
+    else:
+        async with httpx.AsyncClient() as c:
+            response = await c.get(url, timeout=timeout)
+
+    response.raise_for_status()
+    return response.json()
+
+
+async def fetch_claim(
+    hap_id: str,
+    issuer_domain: str,
+    timeout: float = 10.0,
+    client: Optional[httpx.AsyncClient] = None,
+) -> VerificationResponse:
+    """
+    Fetches and verifies a HAP claim from a VA.
+
+    Args:
+        hap_id: The HAP ID to verify
+        issuer_domain: The VA's domain (e.g., "ballista.jobs")
+        timeout: Request timeout in seconds
+        client: Optional httpx client to use
+
+    Returns:
+        The verification response from the VA
+    """
+    if not is_valid_hap_id(hap_id):
+        return {"valid": False, "error": "invalid_format"}
+
+    url = f"https://{issuer_domain}/api/v1/verify/{hap_id}"
+
+    if client:
+        response = await client.get(url, timeout=timeout)
+    else:
+        async with httpx.AsyncClient() as c:
+            response = await c.get(url, timeout=timeout)
+
+    return response.json()
+
+
+def _base64url_decode(data: str) -> bytes:
+    """Decode base64url string to bytes."""
+    import base64
+
+    # Add padding if needed
+    padding = 4 - len(data) % 4
+    if padding != 4:
+        data += "=" * padding
+    return base64.urlsafe_b64decode(data)
+
+
+def _jwk_to_public_key(jwk: HapJwk) -> Ed25519PublicKey:
+    """Convert JWK to Ed25519 public key."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    x_bytes = _base64url_decode(jwk["x"])
+    return Ed25519PublicKey.from_public_bytes(x_bytes)
+
+
+async def verify_signature(
+    jws: str,
+    issuer_domain: str,
+    timeout: float = 10.0,
+    client: Optional[httpx.AsyncClient] = None,
+) -> dict[str, Any]:
+    """
+    Verifies a JWS signature against a VA's public keys.
+
+    Args:
+        jws: The JWS compact serialization string
+        issuer_domain: The VA's domain to fetch public keys from
+        timeout: Request timeout in seconds
+        client: Optional httpx client to use
+
+    Returns:
+        Dict with 'valid' boolean, 'claim' if valid, 'error' if invalid
+    """
+    try:
+        # Fetch public keys from the VA
+        well_known = await fetch_public_keys(issuer_domain, timeout, client)
+
+        # Parse the JWS header to get the key ID
+        header = jwt.get_unverified_header(jws)
+        kid = header.get("kid")
+
+        if not kid:
+            return {"valid": False, "error": "JWS header missing kid"}
+
+        # Find the matching key
+        jwk = next((k for k in well_known["keys"] if k["kid"] == kid), None)
+        if not jwk:
+            return {"valid": False, "error": f"Key not found: {kid}"}
+
+        # Convert JWK to public key
+        public_key = _jwk_to_public_key(jwk)
+
+        # Verify the signature using PyJWT
+        claim = jwt.decode(
+            jws,
+            public_key,
+            algorithms=["EdDSA"],
+            options={"verify_aud": False},
+        )
+
+        # Verify the issuer matches
+        if claim.get("iss") != issuer_domain:
+            return {
+                "valid": False,
+                "error": f"Issuer mismatch: expected {issuer_domain}, got {claim.get('iss')}",
+            }
+
+        return {"valid": True, "claim": claim}
+
+    except Exception as e:
+        return {"valid": False, "error": str(e)}
+
+
+async def verify_hap_claim(
+    hap_id: str,
+    issuer_domain: str,
+    verify_sig: bool = True,
+    timeout: float = 10.0,
+    client: Optional[httpx.AsyncClient] = None,
+) -> Optional[HapClaim]:
+    """
+    Fully verifies a HAP claim: fetches from VA and optionally verifies signature.
+
+    Args:
+        hap_id: The HAP ID to verify
+        issuer_domain: The VA's domain
+        verify_sig: Whether to verify the cryptographic signature
+        timeout: Request timeout in seconds
+        client: Optional httpx client to use
+
+    Returns:
+        The claim if valid, None if not found or invalid
+    """
+    # Fetch the claim from the VA
+    response = await fetch_claim(hap_id, issuer_domain, timeout, client)
+
+    # Check if valid
+    if not response.get("valid"):
+        return None
+
+    # Optionally verify the signature
+    if verify_sig and "jws" in response:
+        sig_result = await verify_signature(response["jws"], issuer_domain, timeout, client)
+        if not sig_result.get("valid"):
+            return None
+
+    return response.get("claims")
+
+
+def extract_hap_id_from_url(url: str) -> Optional[str]:
+    """
+    Extracts the HAP ID from a verification URL.
+
+    Args:
+        url: The verification URL (e.g., "https://www.ballista.jobs/v/hap_abc123xyz456")
+
+    Returns:
+        The HAP ID or None if not found
+    """
+    try:
+        parsed = urlparse(url)
+        path_parts = parsed.path.split("/")
+        last_part = path_parts[-1] if path_parts else ""
+
+        if is_valid_hap_id(last_part):
+            return last_part
+
+        return None
+    except Exception:
+        return None
+
+
+def is_claim_expired(claim: HapClaim) -> bool:
+    """
+    Checks if a claim is expired.
+
+    Args:
+        claim: The HAP claim to check
+
+    Returns:
+        True if the claim has an exp field and is expired
+    """
+    exp = claim.get("exp")
+    if not exp:
+        return False
+
+    exp_date = datetime.fromisoformat(exp.replace("Z", "+00:00"))
+    return exp_date < datetime.now(timezone.utc)
+
+
+def is_claim_for_recipient(claim: HapClaim, recipient_domain: str) -> bool:
+    """
+    Checks if the claim target matches the expected recipient.
+
+    Args:
+        claim: The HAP claim to check
+        recipient_domain: The expected recipient domain
+
+    Returns:
+        True if the claim's target domain matches
+    """
+    claim_type = claim.get("type")
+
+    if claim_type == "human_effort":
+        to = claim.get("to", {})
+        return to.get("domain") == recipient_domain
+
+    if claim_type == "recipient_commitment":
+        recipient = claim.get("recipient", {})
+        return recipient.get("domain") == recipient_domain
+
+    return False

human_attestation-0.3.6/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "human-attestation"
+version = "0.3.6"
+description = "Official SDK for HAP (Human Attestation Protocol) - cryptographic proof of verified human effort"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+    { name = "BlueScroll Inc." }
+]
+keywords = [
+    "hap",
+    "human-attestation-protocol",
+    "attestation",
+    "verification",
+    "proof-of-effort",
+    "cryptographic",
+    "ed25519",
+    "jws",
+    "sender-verification"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "PyJWT>=2.8.0",
+    "cryptography>=41.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Blue-Scroll/hap"
+Repository = "https://github.com/Blue-Scroll/hap.git"
+Documentation = "https://github.com/Blue-Scroll/hap#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["hap"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true