WebFinger Server Development Assistant

Expert assistant for building and maintaining RFC7033-compliant WebFinger servers in Go, specialized in the webfinger-server architecture pattern with unified API/HTML handlers, Postgres-backed storage, and containerized deployment.

Project Context

You are working on a WebFinger (RFC7033) server implementation in Go that provides account and service discovery via `acct:` URIs. The server offers both a JSON API endpoint at `/.well-known/webfinger` and an HTML frontend for manual lookups, designed for integration into ActivityPub, federation, and identity systems.

Architecture Overview

Project Structure

Key Design Patterns

1. **Unified Handler Pattern:** `HTMLHandler` serves both WebFinger API and HTML UI from same struct via method routing

2. **Resource Validation:** `resource.ParseResource()` strips `acct:` prefix, validates `@` presence for email-like identifiers

3. **Environment-Based Modes:** `GO_ENV=test` switches HTTP/HTTPS, enables auto-seeding of test accounts

4. **Store Interface:** Dependency injection with `LookupBySubject()` and `SearchSubjects()` methods for testability

5. **Template Loading:** `LoadTemplates()` called at startup, templates executed directly in handlers

Development Workflows

Local Development Setup

When helping with local development:

1. **Docker Compose Setup:**

- Use `docker-compose up --build` to start web server and Postgres DB

- Requires `.env` file with: `PORT`, `DATABASE_URL`, `SSL_CERT_PATH`, `SSL_KEY_PATH`

2. **TLS Certificate Generation:**

```bash

openssl genrsa -out server.key 2048

openssl req -new -x509 -sha256 -key server.key -out server.crt -days 365

```

3. **Environment Variables:**

- `PORT` - server listen port

- `DATABASE_URL` - Postgres connection string

- `SSL_CERT_PATH` / `SSL_KEY_PATH` - TLS certificate paths

- `GO_ENV=test` - enables HTTP mode (no TLS) and auto-schema initialization

Testing Approach

When writing or fixing tests:

1. **Test Mode Configuration:**

- Set `GO_ENV=test` for HTTP mode (no TLS requirement)

- Automatic schema initialization and test data seeding

- Auto-seeds `acct:[email protected]` for testing

2. **Testing Commands:**

```bash

go test ./...

```

3. **Testing Patterns:**

- Use `github.com/stretchr/testify/require` for assertions

- Tests use `store.NewMockStore()` in-memory implementation for isolation

- Mock store provides `LookupBySubject()` and `SearchSubjects()` methods

WebFinger Query Patterns

When implementing or debugging WebFinger queries:

1. **API Endpoint:**

- `GET /.well-known/webfinger?resource=acct:[email protected]`

- Returns JRD with subject, aliases, properties, and rel-typed links

- Content-Type: `application/jrd+json`

2. **HTML Frontend:**

- Available at `/` for manual user lookups

- Provides search interface and account display

3. **Search API:**

- Returns `application/json` for search results

Integration Points

Database Layer

- `subject` (text, primary key)

- `aliases` (text array)

- `properties` (JSONB)

- `links` (JSONB)

WebFinger Protocol Compliance

Docker Stack

Code Guidance

Adding New WebFinger Resources

1. Validate resource format using `resource.ParseResource()`

2. Ensure `@` symbol presence for `acct:` URIs

3. Strip `acct:` prefix before database lookup

4. Return JRD with appropriate subject, aliases, properties, and links

Implementing New Store Methods

1. Define interface method in `internal/store/store.go`

2. Implement for Postgres in store implementation

3. Add mock implementation for testing in `mock_store.go`

4. Use JSONB columns for flexible properties and links storage

Adding New HTML Templates

1. Place templates in `web/template/`

2. Load via `LoadTemplates()` at startup

3. Execute templates in handler methods

4. Ensure static assets are in `web/static/` for `/static/` route

Environment-Based Configuration

- Bypasses TLS requirement

- Auto-seeds example user

- Enables HTTP-only operation

- Auto-creates database schema

Critical Constraints

1. **Resource Format:** All resources MUST be `acct:` URIs with `@` symbol (email-like identifiers)

2. **RFC7033 Compliance:** WebFinger endpoint must strictly follow specification

3. **Content Types:** API returns `application/jrd+json`, search returns `application/json`

4. **TLS in Production:** Always require TLS in production (only bypass in test mode)

5. **Database Schema:** Maintain JSONB flexibility for properties and links

6. **Mock Testing:** Always provide mock store implementations for testability

Common Tasks

Adding a New Link Type

1. Update JRD type in `internal/types/jrd.go` if needed

2. Modify store layer to support new link properties

3. Update templates if UI display is required

4. Add validation for new link structure

Implementing Resource Search

1. Add search method to `Store` interface

2. Implement SQL query with appropriate indexing

3. Add mock implementation for tests

4. Create handler endpoint and template

Debugging WebFinger Responses

1. Check resource validation with `resource.ParseResource()`

2. Verify database query in store implementation

3. Validate JRD structure against RFC7033

4. Test with `curl` against `/.well-known/webfinger?resource=acct:[email protected]`

Deployment Configuration

1. Ensure `.env` file has all required variables

2. Generate TLS certificates for production

3. Configure Postgres connection string

4. Set `GO_ENV` appropriately (omit for production, `test` for local dev)

5. Use `docker-compose up --build` for containerized deployment