webfinger-server

A minimal, spec-compliant WebFinger server for account and service discovery.

Implements RFC 7033 for WebFinger discovery, designed to be small, auditable, and easy to deploy.

ℹ️ This project was previously named asdf. The name was changed to better reflect its purpose.

Quick curl example

curl "http://localhost:8080/.well-known/webfinger?resource=acct:alice@example.com"

{
  "subject": "acct:alice@example.com",
  "aliases": [
    "https://example.com/users/alice"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@alice"
    }
  ]
}

Description

A WebFinger server implementation following RFC7033, with optional user management, authentication, caching, monitoring, and administrative capabilities.

Features

Core WebFinger

• ✅ RFC7033-compliant WebFinger endpoint (/.well-known/webfinger)
• ✅ rel parameter filtering (RFC 7033 section 4.3)
• ✅ acct: and generic URI resources (https://..., mailto:...)
• ✅ Standalone mode: serve records from a JSON file with zero dependencies
• ✅ JSON Resource Descriptor (JRD) responses
• ✅ Subject aliases and properties support
• ✅ Rel-typed links for social media verification
• ✅ HTML frontend for manual lookups

Authentication & User Management

• ✅ JWT-based authentication with session management
• ✅ User registration and login system
• ✅ Password hashing with bcrypt
• ✅ Role-based access control (admin/user)
• ✅ Email verification support
• ✅ Session management with Redis storage

Performance & Scalability

• ✅ Redis caching for WebFinger lookups
• ✅ Rate limiting with configurable limits
• ✅ Database connection pooling
• ✅ Graceful shutdown handling
• ✅ Request/response compression

Security

• ✅ CORS configuration
• ✅ Security headers (CSP, HSTS, X-Frame-Options)
• ✅ HTTPS redirection (production mode)
• ✅ Input validation and sanitization
• ✅ Trusted proxy configuration

Monitoring & Operations

• ✅ Prometheus metrics collection
• ✅ Structured JSON logging
• ✅ Health check endpoints
• ✅ Database migration system
• ✅ Admin dashboard with user management
• ✅ System statistics and monitoring

Developer Experience

• ✅ Environment-based configuration
• ✅ Docker Compose setup with all dependencies
• ✅ Comprehensive test suite
• ✅ API documentation (OpenAPI/Swagger ready)
• ✅ Development vs production modes

Quick Start

Standalone (Recommended): one binary + one JSON file

No database, no Redis, nothing else. Put your records in data/data.json and run:

go build -o webfinger-server ./cmd/webfinger-server
WEBFINGER_SERVER_ENV=development ./webfinger-server

curl "http://localhost:8080/.well-known/webfinger?resource=acct:example@example.com"

Each entry in the data file is a JRD record:

[
  {
    "subject": "acct:alice@example.com",
    "aliases": ["https://example.com/@alice"],
    "links": [
      {"rel": "http://webfinger.net/rel/profile-page", "type": "text/html", "href": "https://example.com/@alice"}
    ]
  }
]

For production, run behind your HTTPS reverse proxy (Caddy, nginx, Traefik) or set WEBFINGER_SERVER_CERT_PATH / WEBFINGER_SERVER_KEY_PATH for built-in TLS. This mode is the default whenever no database URL is configured.

Database mode with Docker Compose (optional)

Enables PostgreSQL-backed records, user accounts, JWT auth, and the admin features.

1. Clone and setup:

   git clone https://github.com/0dayfall/webfinger-server.git
   cd webfinger-server
   cp .env.example .env

2. Generate certificates:

   openssl genrsa -out server.key 2048
   openssl req -new -x509 -sha256 -key server.key -out server.crt -days 365
   mkdir -p certs && mv server.* certs/

3. Generate secrets:

   # Generate JWT and session secrets
   echo "WEBFINGER_AUTH_JWT_SECRET=$(openssl rand -base64 32)" >> .env
   echo "WEBFINGER_AUTH_SESSION_SECRET=$(openssl rand -base64 32)" >> .env

4. Start services:

   docker-compose up --build

Manual Installation

1. Prerequisites:

   • Go 1.23+
   • PostgreSQL 16+ (only for database mode)
   • Redis 7+ (optional cache, only used in database mode)

2. Build and run:

   go mod download
   go build -o webfinger-server ./cmd/webfinger-server
   ./webfinger-server

Configuration

Configuration can be provided via:

• Environment variables (prefixed with WEBFINGER_)
• YAML configuration file (config.yaml)
• Command line arguments

Key Configuration Options

server:
  port: "8080"
  host: "0.0.0.0"
  env: "development"  # development, production, test

database:
  url: "postgres://user:pass@localhost/webfinger"
  max_open_conns: 25

redis:
  url: "redis://localhost:6379"
  password: ""
  db: 0

auth:
  jwt_secret: "your-secret-key"
  session_secret: "your-session-secret"
  token_expiry_hours: 24

security:
  rate_limit_rps: 10
  rate_limit_burst: 20
  allowed_origins: ["*"]
  enable_csp: true
  enable_hsts: true
  force_https: true

See .env.example for all available options.

API Endpoints

WebFinger

• GET /.well-known/webfinger?resource=acct:user@domain.com - WebFinger lookup

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/logout - User logout
• POST /api/auth/refresh - Token refresh
• GET /api/profile - Get current user profile

Search

• GET /api/search?q=query - Search users

Admin (Requires Admin Role)

• GET /api/admin/stats - System statistics
• GET /api/admin/users - List users
• POST /api/admin/users - Create user
• GET /api/admin/users/{id} - Get user
• PUT /api/admin/users/{id} - Update user
• DELETE /api/admin/users/{id} - Delete user

Monitoring

• GET /health - Health check
• GET /metrics - Prometheus metrics

Development

Running Tests

go test ./...

Database Migrations

# Run migrations
go run cmd/migrate/main.go up

# Rollback last migration  
go run cmd/migrate/main.go down

# Create new migration
go run cmd/migrate/main.go create add_new_feature

Environment Modes

• Development (WEBFINGER_SERVER_ENV=development): HTTP server, auto-migrations, seed data
• Test (WEBFINGER_SERVER_ENV=test): In-memory database, HTTP server, auto-cleanup
• Production (WEBFINGER_SERVER_ENV=production): HTTPS server, manual migrations, security headers

Monitoring

The server exposes Prometheus metrics at /metrics:

• HTTP request metrics (duration, status codes, paths)
• WebFinger-specific metrics (requests, cache hits/misses)
• Database connection metrics
• Authentication metrics (login attempts, active sessions)

Using with Grafana

1. Start monitoring stack:

   docker-compose up prometheus grafana

2. Access Grafana: http://localhost:3000 (admin/admin)

3. Add Prometheus datasource: http://prometheus:9090

Security Considerations

• Change default JWT and session secrets in production
• Use strong TLS certificates in production
• Configure proper CORS origins (not *)
• Set up trusted proxy headers correctly
• Enable security headers (CSP, HSTS)
• Use rate limiting appropriate for your traffic
• Regularly backup your database
• Monitor authentication attempts and failed logins

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

GNU General Public License v3.0 - see LICENSE file for details.