A mission of The Carpocratian Church of Commonality and Equality.

🕊️ Freebird

Authorization without identity. Privacy without compromise.

Freebird is infrastructure for a world without surveillance. It provides cryptographic proof of authorization without revealing identity—separating "can you?" from "who are you?" for the first time in a practical, deployable way.

Think of it as anonymous digital cash for the internet. Users receive unforgeable, unlinkable tokens that prove authorization while revealing nothing about their identity.

---

The Problem

Every online interaction today demands identity:

• Rate limiting requires tracking users
• Access control requires accounts
• Spam prevention requires surveillance
• Resource allocation requires registration

We've accepted total surveillance as the price of functional systems. This is a false choice.

The Solution

Freebird uses VOPRF (Verifiable Oblivious Pseudorandom Function) cryptography to enable:

• ✅ Prove you're authorized without revealing who you are
• ✅ Rate limiting without tracking
• ✅ Access control without accounts
• ✅ Spam prevention without surveillance
• ✅ One person, one vote—anonymously

This isn't just "privacy-preserving rate limiting." It's a new primitive for authorization that makes identity optional rather than mandatory.

---

🖥️ System Requirements

Freebird is lightweight but has specific architectural requirements for security in production environments.

Hardware Sizing

Resources depend on your anticipated user base and Sybil resistance complexity.

Deployment Size	Users	CPU	RAM	Disk
Small	< 1k	2 vCPU	1.5 GB	10 GB SSD
Medium	10k	4 vCPU	3 GB	20 GB SSD
Large	10k+	8+ vCPU	6 GB+	High-Perf SSD

• CPU: Primary bottleneck is cryptographic operations (P-256 scalar multiplication).
• RAM: Includes overhead for Issuer, Verifier, and Redis.
• Disk: State files are small (~1KB/user), but SSDs are recommended for database latency.

Network Architecture

• Development: Issuer and Verifier can run on the same host (e.g., via Docker Compose).
• Production: Issuer and Verifier MUST be deployed on separate infrastructure (different servers or VPCs) to prevent timing attacks and ensure user anonymity.
• Time Sync: System clocks must be synchronized via NTP. The default skew tolerance is 300 seconds (5 minutes).

Software Environment

• Container Runtime: Docker & Docker Compose (Recommended).
• Operating System: Linux (Debian Bookworm is the reference OS).
• Dependencies:
  • Redis: Required for the Verifier (replay protection) and WebAuthn storage in production.
  • Reverse Proxy: Nginx, Caddy, or Cloud LB required for TLS termination.
  • Entropy: System must provide sufficient entropy (>1000 available) for key generation.

Build Requirements

• Docker: Recommended for deployment
• Rust 1.70+: If building from source
• System Entropy: > 1000 (check with cat /proc/sys/kernel/random/entropy_avail)

---

Technical Implementation

Architecture

┌─────────┐                    ┌─────────┐                    ┌──────────┐
│  User   │                    │ Issuer  │                    │ Verifier │
└────┬────┘                    └────┬────┘                    └────┬─────┘
     │                              │                              │
     │  1. Blind(input)             │                              │
     ├──────────────────────────────►                              │
     │                              │                              │
     │  2. Evaluate(blinded) + DLEQ │                              │
     │◄──────────────────────────────                              │
     │                              │                              │
     │  3. Finalize → token         │                              │
     │                              │                              │
     │  4. Present anonymous token  │                              │
     ├──────────────────────────────┼──────────────────────────────►
     │                              │                              │
     │  5. ✓ Authorized (or ✗)      │                              │
     ◄──────────────────────────────┼───────────────────────────────

Cryptographic Properties

• Unlinkability: Mathematical guarantee via VOPRF—issuer cannot correlate token issuance with usage.
• Unforgeability: Only the issuer's private key can create valid tokens.
• Verifiability: DLEQ proofs ensure correct token generation using the committed key.
• Single-Use: Nullifier-based replay protection ensures tokens are spent exactly once.

Implementation Status (v0.1.0)

Core Features:

• ✅ P-256 VOPRF with DLEQ proofs
• ✅ Batch Issuance: High-throughput parallel issuance using rayon
• ✅ Key Rotation: Zero-downtime rotation with grace periods for deprecated keys
• ✅ Storage Backends: In-memory (dev) and Redis (prod) support
• ✅ Multi-Issuer Federation: Signature-based tokens enable verifiers to authenticate tokens from multiple issuers (see FEDERATION.md)
• ✅ Web Admin Dashboard: Modern single-page UI for system management, user administration, and key rotation
• ✅ Admin API: HTTP endpoints for user management, key rotation, and stats

Sybil Resistance Mechanisms:

• ✅ Invitation System: Cryptographically signed invites with ban-trees and reputation tracking
• ✅ Proof of Work: Configurable computational cost
• ✅ Rate Limiting: IP or fingerprint-based throttling
• ✅ WebAuthn/FIDO2: Hardware-backed "Proof of Humanity" (Feature flagged)
• ✅ Combined: Stack multiple mechanisms for defense-in-depth

---

📦 Client SDKs

Freebird includes a fully typed TypeScript/JavaScript SDK for browser and Node.js environments.

JavaScript / TypeScript

npm install @freebird/sdk

import { FreebirdClient } from '@freebird/sdk';

const client = new FreebirdClient({
  issuerUrl: 'https://issuer.example.com',
  verifierUrl: 'https://verifier.example.com'
});

// 1. Initialize (fetch keys)
await client.init();

// 2. Issue an anonymous token
const token = await client.issueToken();
console.log('Got token:', token.tokenValue);

// 3. Verify (or send to third-party)
const isValid = await client.verifyToken(token);

---

🖥️ Web Admin Dashboard

Freebird includes a modern, single-page web interface for managing your deployment—no command-line required.

Features

📊 Dashboard Tab:

• View real-time system statistics
• Monitor user counts, invitations, and redemptions
• Track banned users and system health
• One-click refresh

👥 User Management Tab:

• View all users with search and filtering
• Inspect detailed user profiles and reputation scores
• View invitation trees and relationships
• Ban individual users or entire invitation trees

🎫 Invitations Tab:

• Create cryptographically signed invitation codes
• Grant invitation quota to users
• View invitation history and redemption status
• Copy codes and signatures with one click

🔑 Key Management Tab:

• View active and deprecated cryptographic keys
• Rotate keys with configurable grace periods
• Clean up expired keys
• Monitor key status and expiration

Access

Once your Freebird issuer is running, access the dashboard at:

http://localhost:8081/admin

Authentication: Requires the ADMIN_API_KEY from your .env file (minimum 32 characters).

Architecture

• Zero dependencies: Single HTML file with embedded CSS and JavaScript
• No build step: Served directly from the issuer binary
• Minimal footprint: ~1300 lines including all features
• Modern UI: Clean, responsive design using water.css
• Secure: API key stored in browser localStorage only

📖 Complete Admin Dashboard Documentation →

---

Quick Start

🐳 Docker (Recommended)

The fastest way to get Freebird running is with Docker:

git clone https://github.com/yourusername/freebird.git
cd freebird

# Copy and optionally customize the environment configuration
cp .env.example .env

# Start all services (Issuer, Verifier, Redis)
docker compose up --build

That's it! Freebird is now running:

• Issuer: http://localhost:8081
• Verifier: http://localhost:8082
• 🖥️ Web Admin Dashboard: http://localhost:8081/admin (Full-featured UI for system management)
• Admin API: http://localhost:8081/admin/* (REST API, requires ADMIN_API_KEY)

Verify deployment:

curl http://localhost:8081/.well-known/issuer

📖 Read the complete Docker Quickstart Guide →

The guide includes:

• Detailed configuration options
• API examples (cURL, TypeScript SDK, Rust CLI)
• Troubleshooting common issues
• Production deployment checklist

🦀 Build from Source

# Prerequisites: Rust 1.70+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build all components
cargo build --release

# Terminal 1: Start Issuer
./target/release/issuer

# Terminal 2: Start Verifier
./target/release/verifier

# Terminal 3: Run the CLI Interface to test the flow
./target/release/interface --stress 5

---

Configuration

Freebird is configured via environment variables. For Docker deployments, use the .env file.

Quick Configuration

# Copy the example configuration
cp .env.example .env

# Edit with your preferred editor
nano .env

The .env.example file contains all available configuration options with detailed comments and sensible defaults.

Key Configuration Variables

Issuer:

Variable	Default	Description
ISSUER_ID	issuer:freebird:v1	Unique identifier for this issuer
BIND_ADDR	0.0.0.0:8081	Listening address
SYBIL_RESISTANCE	none	invitation, pow, rate_limit, webauthn, combined, etc.
ADMIN_API_KEY	(None)	Required for Admin API (min 32 chars)
EPOCH_DURATION_SEC	86400	Key rotation epoch duration (seconds)

Verifier:

Variable	Default	Description
ISSUER_URL	http://localhost:8081/.well-known/issuer	Issuer metadata URL
REDIS_URL	(None)	Redis URL for persistent nullifier storage
MAX_CLOCK_SKEW_SECS	300	Clock skew tolerance (seconds)

📖 See .env.example for the complete configuration reference with all 56+ available options.

---

Security Model

Guarantees

• ✅ Cryptographic Unlinkability: The issuer creates a blind signature. Even if the issuer and verifier collude, they cannot mathematically link the issuance request to the verification request.
• ✅ Forward Privacy: Key rotation ensures that if a key is eventually compromised, past sessions remain secure.
• ✅ Replay Protection: The verifier maintains a nullifier set (in Redis or memory) to prevent double-spending.
• ✅ No Phone-Home: The system is fully self-contained.

Not Protected Against

• Token Theft: Bearer tokens can be stolen if sent over insecure channels (use TLS!).
• Network Correlation: An observer seeing a request enter the issuer and immediately exit to the verifier might correlate them via timing (use Tor/mixnets for network anonymity).
• Quantum Adversaries: Relies on the hardness of the Discrete Log Problem on P-256.

---

License

Apache License 2.0

Copyright 2025 The Carpocratian Church of Commonality and Equality, Inc.

---

"Surveillance is not safety. Privacy is not crime. Authorization is not identity."

🕊️