human-proof

⬡ Human-Proof

Privacy-First Protocol for Hardware-Verified Human Liveness

Human-Proof is an open-source protocol and SDK designed to solve the problem of automated bot abuse (sybil attacks, spam, voting manipulation) by shifting the security perimeter from Identity to Physical Presence.

By leveraging native WebAuthn (FIDO2) capabilities, Human-Proof generates cryptographic proofs that an action was performed by a human physically interacting with a hardware Root of Trust (Secure Enclave, TPM), without ever collecting biometrics or PII.

⚡ Key Features

• Privacy-Preserving: Zero-knowledge liveness. No fingerprints, facial data, or IDs leave the user's device.
• Bot-Resistant: Neutralizes AI agents and headless browsers by requiring hardware-backed assertions.
• Pluggable Storage: Use the default MemoryStore or implement the IHumanStore for Redis, SQL, or MongoDB.
• Hardware Trust Tiers: Distinguish between high-security smartphones (Secure Enclave) and standard authenticators.
• Zero-Dependency SDK: Lightweight browser SDK with no external dependencies.
• Developer-Centric: Simple Express middleware and React-friendly hooks.

🏗️ Architecture

Human-Proof operates as a stateless challenge-response protocol:

• Enrollment: User registers a "Human-Key" on their device's secure hardware.
• Challenge: Server issues an action-scoped, short-lived (60s) challenge.
• Assertion: User provides a biometric/PIN-unlocked signature from the hardware module.
• Verification: Server validates the signature and hardware attestation to confirm liveness.

Explore the Architecture Docs for sequence diagrams and deep dives.

🚀 Getting Started

Installation

npm install human-proof

Server-Side Configuration (Express)

import { HumanProof, createHumanProofMiddleware } from "human-proof/server";

const humanProof = new HumanProof({
  rpId: "example.com",
  rpName: "My Application"
});

const requireHuman = createHumanProofMiddleware(humanProof);

// Protect sensitive endpoints
app.post("/api/vote", requireHuman("vote:submit"), (req, res) => {
  const { result } = req.humanProof!;
  res.json({ success: true, trustTier: result.trustTier });
});

Automated Human Verification

import { HumanProofSDK } from "human-proof";

const sdk = new HumanProofSDK({ rpId: "example.com" });

// Automatically attaches human liveness proof to the request
await sdk.protectedFetch("/api/secure-action", {
  method: "POST",
  body: JSON.stringify({ data: "..." }),
  action: "secure:execute"
});

React Hook integration

import { useHumanProof } from "human-proof";

function VoteButton() {
  const { execute, isBusy } = useHumanProof({ rpId: "example.com" });
  
  const handleVote = async () => {
    await execute("vote:submit", async () => {
      // Your protected API call here
    });
  };

  return <button onClick={handleVote} disabled={isBusy}>Vote</button>;
}

Client-Side (Browser SDK)

import { HumanProofSDK } from "human-proof/sdk";

const sdk = new HumanProofSDK({ rpId: "example.com" });

// Enrollment (once per device)
await sdk.enroll({ userId: "[e-mail]" });

// Protected Action
await sdk.protectedFetch("/api/vote", {
  method: "POST",
  body: JSON.stringify({ choice: "A" }),
  action: "vote:submit"
});

📖 Documentation

• Problem Statement: Why presence verification matters in the AI era.
• User Stories: Stakeholder outcomes and use cases.
• Security Model: Threat analysis and mitigation strategies.
• API Reference: Automatically generated technical documentation.

🧪 Development & Testing

We use Vitest for testing and tsup for high-performance builds.

npm install     # Install dev dependencies
npm test        # Run unit tests
npm run dev     # Launch the premium demo server (http://localhost:3000)
npm run build   # Generate dual-mode (ESM/CJS) bundles

⚖️ License

MIT © Human-Proof Team