HAP - Human Attestation Protocol

Built to prove your effort matters.

Proof of human effort for the AI age.

When AI makes personalized outreach nearly as cheap as mass spam, proving you're real becomes a competitive advantage. HAP is the open standard for verified human effort.

When sending a message costs nothing, messages mean nothing.

The pattern repeats: friction is removed, volume explodes, signal drowns, recipients stop paying attention.

AI accelerates this dramatically. The cost of faking sincerity dropped significantly.

HAP doesn't detect AI. It verifies that a human took costly action.

We can't detect AI-generated content. But we can verify that someone:

• Spent real money
• Invested real time
• Moved physical atoms

Effort suggests intent. A cryptographic signature proves someone invested real money and time—but that alone doesn't guarantee quality, honesty, or good intentions. It's a signal that cuts through automated noise, not a vetting process.

A Verification Authority (VA) confirms you did something hard to fake. They sign a cryptographic claim. Recipients verify the signature. The claim is the proof.

Sender    →  Takes costly action (sends mail, pays fee, completes interview)
VA        →  Signs verification claim
Message   →  Includes claim (QR code, URL, or header)
Recipient →  Verifies signature, sees proof of effort

No API calls required to verify. Once you have a VA's public keys (published at /.well-known/hap.json), verification happens offline. The signature is the proof.

For the full philosophy, see docs/vision.md.

Without a protocol, every verification service is a walled garden. Your proof only works where that vendor has integrations.

HAP changes this:

This is the same shift that created email (SMTP), the web (HTTP), and secure connections (TLS). Open protocol, competitive ecosystem, trust earned by implementations.

HAP provides the common language. VAs compete on service quality.

Anyone can implement HAP. No approval required. See Becoming a VA.

Integrate once, accept claims from any VA. No approval required. See HAP for Recipients.

import { verifyClaim, isClaimExpired, isClaimForRecipient } from "human-attestation";

const claim = await verifyClaim("hap_abc123xyz456", "ballista.jobs");
if (claim && !isClaimExpired(claim) && isClaimForRecipient(claim, "yourorg.com")) {
  console.log(`Verified: ${claim.method} → ${claim.to.name}`);
}

# Fetch claim
curl https://www.ballista.jobs/api/v1/verify/hap_abc123xyz

# Fetch VA's public keys
curl https://www.ballista.jobs/.well-known/hap.json

# Verify Ed25519 signature locally

Official SDKs handle key fetching, signature verification, and claim validation:

See packages/ for complete SDK documentation.

Verification Authorities (VAs) are services that verify human effort and sign HAP claims.

See directory/ for the machine-readable list and listing criteria.

Note: Listing in the directory means a VA has published a valid HAP endpoint. Trust decisions remain with you—evaluate each VA's verification methods and reputation for your use case. External links may change; verify current VA websites directly.

• Cryptography: Ed25519 signatures (fast, small, no parameter negotiation attacks)
• Format: JWS Compact Serialization
• Offline: Claims verify without network calls once you have public keys
• Compact: QR-friendly format fits in ~280 characters

HAP is a specification, not infrastructure. No central server. Each VA hosts their own endpoints.

See SPEC.md for complete technical details.

• Identity verification — We verify effort, not who you are
• Content verification — AI can help write; the effort to send is what matters
• Trust authority — The protocol places no restrictions on who can become a VA; you decide which VAs to trust
• Quality guarantee — Verified effort ≠ good content

• Full Specification — Technical details, claim formats, cryptographic requirements
• Vision & Philosophy — Why HAP exists and where it's going
• Method Requirements — What makes a verification method HAP-compliant
• For Verification Authorities — How to implement HAP and join the directory

Apache 2.0 — See LICENSE