Homegate

A backend service to gatekeep Pubky Homeserver signups.

The Pubky social media app uses Homegate to gatekeep signups. Check out https://pubky.app/onboarding/human (use a private browser window if you have an active session).

This service depends on

• Prelude as a SMS service provider.
• PhoenixD As a Lightning Payment provider.

Configuration

Homegate is configured via a TOML file. Copy config.toml.example to ~/.homegate/config.toml and fill in the required values. Use --data-dir to specify a different data directory (defaults to ~/.homegate/).

The database_url field must point to an existing PostgreSQL database, e.g.:

database_url = "postgres://postgres:postgres@localhost:5432/pubky_homegate"

Verification routes are optional — include an [sms_verification], [ln_verification], or [ip_verification] section to enable each one. Omitting a section disables that route entirely.

See config.toml.example for the full list of options and defaults.

Usage

cargo run
# Or with a custom data directory:
cargo run -- --data-dir /path/to/data

Warning

This code generates a secret which is written to local disk at ~/.homegate/pepper.txt.

If this value is lost then you lose the ability to match phone numbers which have been already verified to phone numbers of new verification requests - this is turn means that the verification limits will not be enforced.

SMS Verification

We use Prelude for SMS verification. Keep in mind that each phone number:

• Has a maximum of 10 verifications.
• Has a single pending verification at a time. Multiple send_code calls reuse the existing session.

Lightning Payment Verification

We use phoenixd for Lightning Payment verifications.

IP Verification

A low-friction alternative to SMS/LN verification. A client POSTs to /ip_verification and receives a signup code if their IP has not exceeded the configured weekly/annual limits.

IP-based rate limiting is inherently easy to circumvent (rotating IPs, VPNs). See src/ip_verification/mod.rs for detailed security considerations.

Enabled by adding an [ip_verification] section to config.toml:

[ip_verification]
max_verifications_per_week = 2   # default
max_verifications_per_year = 4   # default

Running Tests

Tests use the DATABASE_URL env var (a sqlx::test convention) to provision test database pools. This is separate from the database_url field in config.toml which is only used at runtime, tests never load config.toml.

# Run all tests
DATABASE_URL=postgres://postgres:postgres@localhost:5432/pubky_homegate?pubky-test=true cargo test

# Run only E2E HTTP tests
DATABASE_URL=postgres://postgres:postgres@localhost:5432/pubky_homegate?pubky-test=true cargo test --lib e2e::

Test Structure

• Unit Tests: IP extraction logic (src/infrastructure/http/extractors/request_origin.rs)
• Service Tests: Business logic and database operations (src/sms_verification/tests.rs, src/ip_verification/tests.rs)
• E2E Tests: Full HTTP integration tests (src/e2e/)