🕊️ 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 blind issuance 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

The current prototype has two token modes: V4 private-verification tokens for verifier-bound privacy, and V5 public bearer passes for public-key verification by trusted communities.

---

🖥️ 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 token input        │                              │
     ├──────────────────────────────►                              │
     │                              │                              │
     │  2. Blind-sign / evaluate    │                              │
     │◄──────────────────────────────                              │
     │                              │                              │
     │  3. Finalize → token         │                              │
     │                              │                              │
     │  4. Present anonymous token  │                              │
     ├──────────────────────────────┼──────────────────────────────►
     │                              │                              │
     │  5. ✓ Authorized (or ✗)      │                              │
     ◄──────────────────────────────┼───────────────────────────────

Cryptographic Properties

• Unlinkability: Blind issuance prevents the issuer from seeing the final token it signs.
• Unforgeability: Only the issuer's private key can create valid tokens.
• Two Verification Modes: V4 uses private VOPRF verification; V5 uses public RFC 9474 blind RSA signatures.
• Single-Use: Nullifier-based replay protection ensures tokens are spent exactly once.

Implementation Status

Core Features:

• ✅ P-256 VOPRF with DLEQ proofs
• ✅ V4 Private Option: Verifier-bound private verification with local authenticator recomputation
• ✅ V5 Public Option: RFC 9474 public bearer passes with strict single_use key metadata
• ✅ 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
• ✅ Explicit Issuer Trust: Verifiers accept only configured issuers, with V4 private keys or V5 public key metadata (see FEDERATION.md)
• ✅ Unified Admin Dashboard: Single-page UI for both issuer and verifier management
• ✅ Admin CLI: freebird-cli command-line tool for scripting and automation
• ✅ Admin API: HTTP endpoints for user management, key rotation, and stats
• ✅ Prometheus Metrics: /admin/metrics endpoint for monitoring and alerting
• ✅ Config Validation: Pre-flight configuration checker

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" with attestation policies, discoverable credentials, and credential management
• ✅ 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' // fetches verifier scope metadata
});

// 1. Initialize (fetch issuer keys and verifier scope)
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);

---

🖥️ Command-Line Interface

Freebird includes freebird-cli, a command-line tool for managing your deployment programmatically.

Installation

# From source
cargo install --path issuer --bin freebird-cli

# Or use the Docker image
docker run --rm freebird/cli --help

Configuration

# Set connection details via environment
export FREEBIRD_ISSUER_URL=http://localhost:8081
export FREEBIRD_ADMIN_KEY=your-admin-key

# Or pass via CLI flags
freebird-cli --url http://localhost:8081 --key your-admin-key <command>

Commands

# System
freebird-cli health              # Check issuer health
freebird-cli stats               # Show statistics
freebird-cli config              # Show configuration
freebird-cli metrics             # Show Prometheus metrics
freebird-cli audit               # View audit log

# User Management
freebird-cli users list          # List all users
freebird-cli users get <id>      # Get user details
freebird-cli users ban <id>      # Ban a user
freebird-cli users ban <id> --tree  # Ban user and their invite tree

# Invitations
freebird-cli invites list        # List invitations
freebird-cli invites create <user> --count 5  # Create invitations
freebird-cli invites grant <user> --count 3   # Grant invite slots

# Key Management
freebird-cli keys list           # List VOPRF keys
freebird-cli keys rotate         # Rotate VOPRF key
freebird-cli keys cleanup        # Remove expired keys

# Data Export
freebird-cli export users        # Export users to JSON
freebird-cli export invitations  # Export invitations to JSON
freebird-cli export audit        # Export audit log to JSON

Output Formats

# Table output (default)
freebird-cli users list

# JSON output (for scripting)
freebird-cli --format json users list

# Compact output
freebird-cli --format compact stats

---

🖥️ Unified Admin Dashboard

Freebird includes a modern, single-page web interface for managing your deployment. The UI automatically detects which service it's connected to (issuer or verifier) and shows the appropriate features.

Issuer Features

📊 Dashboard Tab:

• Real-time system statistics (users, invitations, redemptions)
• Interactive activity charts with Canvas visualization
• Monitor banned users and system health

👥 User Management Tab:

• Search and filter users
• View detailed user profiles with reputation scores
• Interactive invitation tree visualization
• Ban users individually or recursively (entire invite tree)

🎫 Invitations Tab:

• Create cryptographically signed invitation codes
• Grant invitation quota to users
• Track redemption status and expiration

🔑 Key Management Tab:

• View active and deprecated cryptographic keys
• Rotate keys with configurable grace periods
• Clean up expired keys

⚙️ Sybil Configuration Tab:

• View current Sybil resistance mode and settings
• Monitor resistance mechanism statistics

📋 Audit Logs Tab:

• Comprehensive system activity logs
• Filter by level (info, warning, error, success)
• Search logs by keyword

🔐 WebAuthn Tab:

• Register FIDO2 credentials and security keys
• Manage biometric authentication

Verifier Features

📊 Dashboard Tab:

• Verification statistics and epoch information
• Uptime and store backend status
• Trusted issuer count

🔗 Trusted Issuers Tab:

• View all configured trusted issuers
• Inspect issuer details (public key, context, expiration)
• Trigger issuer metadata refresh

💾 Cache Tab:

• Replay cache statistics
• Cache backend status
• Cache management operations

Access

# Issuer Admin
http://localhost:8081/admin

# Verifier Admin
http://localhost:8082/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 binary
• Service detection: Automatically adapts to issuer or verifier
• Modern UI: Clean, responsive design with dark mode support
• Secure: API key stored in browser localStorage only

📖 Complete Admin Dashboard Documentation →

---

📊 Prometheus Metrics

Freebird exposes metrics in Prometheus text exposition format for monitoring and alerting integration.

Endpoint

curl -H "X-Admin-Key: $ADMIN_API_KEY" http://localhost:8081/admin/metrics

Available Metrics

Metric	Type	Description
freebird_users_total	Gauge	Total registered users
freebird_users_banned	Gauge	Number of banned users
freebird_invitations_total	Gauge	Total invitations created
freebird_invitations_redeemed	Gauge	Total invitations redeemed
freebird_invitations_pending	Gauge	Pending invitations
freebird_keys_total	Gauge	Total signing keys
freebird_keys_active	Gauge	Active signing keys
freebird_keys_deprecated	Gauge	Deprecated signing keys
freebird_keys_expiring_soon	Gauge	Keys expiring within 7 days
freebird_info	Info	Instance metadata with sybil_mode label

Prometheus Configuration

# prometheus.yml
scrape_configs:
  - job_name: 'freebird'
    static_configs:
      - targets: ['localhost:8081']
    metrics_path: /admin/metrics
    authorization:
      type: 'Bearer'
      credentials: 'your-admin-api-key'

---

Quick Start

🐳 Docker (Recommended)

The fastest way to get Freebird running is with Docker.

Option A: Use pre-built images from GitHub Container Registry (no Rust needed):

# Pull the latest pre-built image
docker pull ghcr.io/flammafex/freebird:latest

# Or run the full stack with docker-compose using the pre-built image
git clone https://github.com/flammafex/freebird.git
cd freebird
cp .env.example .env
docker compose up

Option B: Build from source:

git clone https://github.com/flammafex/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/freebird-issuer

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

# Terminal 3: Run the CLI Interface to test the flow
./target/release/freebird-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

# Validate configuration before starting
freebird-validate-config

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

Configuration Validation

Before starting Freebird, validate your configuration:

source .env && freebird-validate-config

This checks for:

• Missing required variables
• Invalid duration formats
• Missing key files
• Common configuration errors

Human-Readable Duration Format

Duration fields support human-readable formats:

Format	Example	Description
Days	30d	30 days
Hours	24h	24 hours
Minutes	30m	30 minutes
Seconds	45s	45 seconds
Combined	1d12h	1 day and 12 hours
Raw	3600	Seconds

Key Configuration Variables

Issuer:

Variable	Default	Description
ISSUER_ID	issuer:freebird:v4	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	1d	Key rotation epoch duration
PUBLIC_BEARER_ENABLE	true	Enable V5 public bearer issuance
PUBLIC_BEARER_SK_PATH	public_bearer_sk.der	V5 RSA blind-signature private key
PUBLIC_BEARER_METADATA_PATH	public_bearer_metadata.json	Immutable V5 public key metadata
PUBLIC_BEARER_AUDIENCE	(None)	Optional V5 audience binding

Verifier:

Variable	Default	Description
ISSUER_URL	http://localhost:8081/.well-known/issuer	Issuer metadata URL (comma-separated for multiple)
VERIFIER_ID	(Required)	Stable verifier scope ID bound into V4 tokens
VERIFIER_AUDIENCE	VERIFIER_ID	Application/API audience bound into V4 tokens
REDIS_URL	(None)	Redis URL for persistent nullifier storage
VERIFIER_SK_B64	(None)	Base64url raw 32-byte key for V4 private verification
VERIFIER_SK_PATH	(None)	File path for V4 private verification key material
VERIFIER_KEYRING_B64	(None)	JSON map of kid to base64url raw keys

📖 See .env.example for the complete configuration reference.

---

Security Model

Guarantees

• ✅ Cryptographic Unlinkability: The issuer signs blinded client input and does not see the final token.
• ✅ Scoped Privacy Options: V4 binds tokens to verifier scope; V5 provides public-key verification for self-hosted communities.
• ✅ 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 2026 The Carpocratian Church of Commonality and Equality, Inc.

---

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

🕊️