Soulprint

Soulprint — Decentralized Identity for AI Agents

Soulprint proves a real human is behind any AI bot using privacy-preserving proofs — no centralized authority, no biometric cloud uploads. Everything runs on-device.

GitHub: https://github.com/manuelariasfz/soulprint
npm: https://www.npmjs.com/package/soulprint
Docs: https://soulprint.digital/docs/

When to Use

✅ USE this skill when:

• "Verify my identity for an AI agent"
• "Run a Soulprint validator node"
• "Add identity verification to my MCP server or API"
• "Check the reputation score of a bot or DID"
• "Generate a privacy proof from a Colombian cédula"
• "Issue or verify an SPT (Soulprint Token)"
• "Enforce a minimum trust threshold that cannot be lowered"

❌ DON'T use this skill when:

• Storing or transmitting biometric data remotely (Soulprint runs 100% locally)
• Verifying identities from countries not yet supported

Quick Start

1. Verify Your Identity (one-time)

# Install local dependencies (OCR + face recognition) — only needed once
npx soulprint install-deps

# Run interactive verification — all local, nothing uploaded
npx soulprint verify-me
# Scans document, runs local face match, generates privacy proof
# Saves identity token to local storage

2. Show Your Token

npx soulprint show
# Output: DID, trust score (0-100), credentials, expiry, proof hash

3. Renew Token

npx soulprint renew

4. Run a Validator Node

# Starts HTTP (port 4888) + P2P network (port 6888) simultaneously
npx soulprint node

Node API endpoints:

GET  /info                — node info and network stats
GET  /protocol            — immutable protocol constants (floors, thresholds)
POST /verify              — verify proof and register anti-replay hash
POST /reputation/attest   — issue bot reputation attestation (+1 / -1)
GET  /reputation/:did     — get current bot reputation score (0-20)
GET  /proof-hash/:hash    — check if a proof hash is registered

Protocol Constants (Immutable — P2P Enforced)

All validator nodes in the network share these constants. They are enforced at two levels:

1. Object.freeze() — prevents runtime modification within a process
2. P2P Network Hash — PROTOCOL_HASH is computed from all constant values. Any modification changes the hash → the node gets rejected by the entire network.

import { PROTOCOL_HASH, isProtocolHashCompatible } from 'soulprint-core';

// Each node computes this at startup from its actual PROTOCOL values
PROTOCOL_HASH  // "dfe1ccca1270ec86f93308dc4b981bab1d6bd74bdcc334059f4380b407ca07ca"

// P2P enforcement: peer registration validates hash
// POST /peers/register { url, protocol_hash } → 409 if mismatch
// Gossip headers: X-Protocol-Hash validated on receive → rejected if different

Check a node's live constants:

curl http://localhost:4888/protocol
# Returns all constants + immutable: true

Integrate in Your API

MCP Server (3 lines)

import { requireSoulprint } from "soulprint-mcp";

server.tool("premium-tool", requireSoulprint({ minScore: 80 }), async (args, ctx) => {
  const { did, score } = ctx.soulprint;
  // only reachable if identity token is valid and score >= 80
  // Note: minScore is auto-clamped to 65 minimum (protocol floor)
});

The minScore option is automatically clamped to the protocol floor:

• requireSoulprint({ minScore: 40 }) → effectively uses 65 (clamped)
• requireSoulprint({ minScore: 80 }) → uses 80 (already above floor)

MCP Server with validator verification + retries

import { requireSoulprint } from "soulprint-mcp";

// Verifies token locally AND confirms with a remote validator node.
// If the validator is temporarily down, retries up to 3 times with backoff,
// then falls back to offline mode automatically.
server.tool(
  "secure-tool",
  requireSoulprint({
    minScore:     80,
    validatorUrl: "http://localhost:4888",
  }),
  async (args, ctx) => {
    const { did, score, reputation } = ctx.soulprint;
    return { content: [{ type: "text", text: `Verified: ${did}` }] };
  }
);

Express / Fastify

import { soulprintMiddleware } from "soulprint-express";

app.use(soulprintMiddleware({ minScore: 65 }));

app.get("/protected", (req, res) => {
  const { did, score } = req.soulprint;
  res.json({ did, score });
});

Token is read from (in order):

1. MCP capabilities header: x-soulprint-token
2. HTTP header: X-Soulprint
3. Bearer authorization header

Trust Score (0–100)

Score floors (enforced by all validator nodes):

• Any service using requireSoulprint() will have its threshold clamped to ≥ 65
• Users with document verified can never drop below 52 total score, regardless of reputation attacks

Default bot reputation: 10/20 (neutral).

Retry Logic

All verification calls to validator nodes automatically retry on failure:

Attempt 1  → immediate
Attempt 2  → wait 500ms
Attempt 3  → wait 1000ms
           → fall back to offline signature-only verification

This is handled transparently by requireSoulprint() when validatorUrl is set. No configuration needed — behavior is defined by protocol constants.

Credential Validators (Open Source, Built-in)

Each validator node comes with real credential verification — no API keys required for most:

Email Verified (nodemailer — SMTP)

# 1. Request OTP
curl -X POST http://localhost:4888/credentials/email/start \
  -d '{"did":"did:soulprint:abc...","email":"user@example.com"}'
# → { sessionId, message: "OTP sent to your email" }

# 2. Verify OTP (6-digit code from email)
curl -X POST http://localhost:4888/credentials/email/verify \
  -d '{"sessionId":"...","otp":"123456"}'
# → { credential: "EmailVerified", did, attestation }

Config: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS (dev: uses Ethereal catch-all, no config needed)

Phone Verified (TOTP — no SMS, no API key)

# 1. Get TOTP setup URI
curl -X POST http://localhost:4888/credentials/phone/start \
  -d '{"did":"did:soulprint:abc...","phone":"+573001234567"}'
# → { sessionId, totpUri, instructions }
# User scans totpUri QR with Google Authenticator / Authy / Aegis

# 2. Verify 6-digit TOTP code
curl -X POST http://localhost:4888/credentials/phone/verify \
  -d '{"sessionId":"...","code":"123456"}'
# → { credential: "PhoneVerified", did, attestation }

No external services — uses RFC 6238 TOTP standard. Works offline.

GitHub Linked (OAuth — native fetch)

# Redirect user to GitHub OAuth
GET http://localhost:4888/credentials/github/start?did=did:soulprint:abc...
# → Redirects to github.com/login/oauth/authorize
# GitHub redirects back to /credentials/github/callback
# → { credential: "GitHubLinked", did, github: { login }, attestation }

Config: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, SOULPRINT_BASE_URL Create OAuth App: https://github.com/settings/applications/new

Biometric Bound (built-in — via verify-me)

Issued automatically when user completes npx soulprint verify-me. No separate endpoint needed — tied to identity proof hash.

Anti-Farming Protection

The reputation system is protected against point farming. If a bot tries to farm points, the +1 is automatically converted to -1.

Rules (immutable, enforced by all validator nodes)

What farming looks like vs. real usage

❌ Farming (detected):
   - Call tool A 3x, tool B 3x, tool C 3x every 60 seconds
   - Regular 2-second intervals (robotic pattern)
   - Same service rewards same DID multiple times/day

✅ Real usage (rewarded):
   - Session lasts > 30 seconds
   - Uses 4+ different tools naturally
   - Variable time between actions
   - Different services on different days

• Proof system: local circuit — 844 logic gates — advanced proof scheme (snarkjs)
• Prove time: ~564ms locally | Verify time: ~25ms
• Anti-replay: unique identity hash per person — prevents double registration
• Privacy guarantee: all sensitive inputs stay on-device; only the proof and its public hash are shared

P2P Network

Validator nodes form a peer-to-peer mesh network:

libp2p v2.10:
  TCP transport + encrypted channels + stream multiplexing
  Kademlia DHT (peer routing)
  GossipSub (attestation broadcast — topic: soulprint-attestations-v1)
  mDNS (local network auto-discovery)

Nodes check protocol compatibility on connect. Nodes with a different protocol version or modified score floors are rejected from the network automatically.

Attestations propagate via GossipSub; HTTP fallback for legacy nodes.

7 npm Packages

Country Support

Want to add your country? See the Contributing Guide.