# Favoritter

A self-hosted web application for collecting and sharing favorites. Movies, songs, cars, lego sets, flowers, pictures — anything you love.

Built as a single Go binary with SQLite, server-rendered HTML, and [HTMX](https://htmx.org/) for interactivity. Designed to be easy to deploy for technical users who can share access with friends and family.

## Features

- **Favorites** — Add favorites with a description, optional URL, optional image upload, and tags
- **Tags** — Autocomplete from existing tags, browse by tag
- **Privacy** — Each favorite can be public or private, with a configurable default
- **User profiles** — Public or limited visibility, with avatar, bio, and display name
- **Admin panel** — User management, tag management, signup request approval, site settings
- **Signup modes** — Open registration, approval-required, or closed
- **Atom feeds** — Global, per-user, and per-tag feeds
- **Import/Export** — JSON and CSV, for data portability
- **JSON API** — Full REST API under `/api/v1/` for third-party clients
- **OpenGraph** — Rich link previews when sharing favorites
- **Accessible** — Semantic HTML, keyboard navigation, screen reader support, `lang="nb"`, WCAG 2.2 AA target
- **Proxy-aware** — Supports deployment behind Caddy/nginx on a different machine (WireGuard, Tailscale)

## Quick Start

### Run directly

```bash
# Build
go build -o favoritter ./cmd/favoritter

# Run (creates admin user on first start)
FAVORITTER_ADMIN_USERNAME=admin \
FAVORITTER_ADMIN_PASSWORD=changeme \
./favoritter
```

Open http://localhost:8080 in your browser.

### Run with Podman/Docker

```bash
BUILDAH_FORMAT=docker podman build \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --build-arg GIT_REVISION="$(git describe --always --dirty)" \
  -t favoritter .

podman run -d \
  -p 8080:8080 \
  -v favoritter-data:/data \
  -e FAVORITTER_ADMIN_USERNAME=admin \
  -e FAVORITTER_ADMIN_PASSWORD=changeme \
  favoritter
```

## Configuration

All configuration is via environment variables. Sensible defaults are provided for everything except the initial admin credentials.

| Variable | Default | Description |
|----------|---------|-------------|
| `FAVORITTER_ADMIN_USERNAME` | *(none)* | Initial admin username (created on first run) |
| `FAVORITTER_ADMIN_PASSWORD` | *(none)* | Initial admin password |
| `FAVORITTER_DB_PATH` | `./data/favoritter.db` | SQLite database file path |
| `FAVORITTER_LISTEN` | `:8080` | Listen address (e.g. `:8080`, `10.0.0.5:8080`) |
| `FAVORITTER_BASE_PATH` | `/` | Base path for subpath deployment (e.g. `/faves`) |
| `FAVORITTER_EXTERNAL_URL` | *(auto)* | Public URL (e.g. `https://faves.example.com`). Used for feeds, cookies, OpenGraph. If unset, inferred from Host header. |
| `FAVORITTER_TRUSTED_PROXIES` | `127.0.0.1` | Comma-separated IPs/CIDRs to trust for `X-Forwarded-For` (e.g. `100.64.0.0/10` for Tailscale) |
| `FAVORITTER_UPLOAD_DIR` | `./data/uploads` | Directory for uploaded images |
| `FAVORITTER_MAX_UPLOAD_SIZE` | `10485760` | Maximum upload size in bytes (10 MB) |
| `FAVORITTER_SESSION_LIFETIME` | `720h` | Session cookie lifetime (30 days) |
| `FAVORITTER_ARGON2_MEMORY` | `65536` | Argon2id memory cost in KiB (64 MB) |
| `FAVORITTER_ARGON2_TIME` | `3` | Argon2id iterations |
| `FAVORITTER_ARGON2_PARALLELISM` | `2` | Argon2id parallelism |
| `FAVORITTER_RATE_LIMIT` | `60` | Auth endpoint rate limit (requests/minute/IP) |
| `FAVORITTER_SITE_NAME` | `Favoritter` | Site name shown in UI and feeds |
| `FAVORITTER_DEV_MODE` | `false` | Enable live template reload and debug logging |

## Deployment

### Behind Caddy (subdomain)

```
faves.example.com {
    reverse_proxy 10.0.0.5:8080
}
```

Set `FAVORITTER_EXTERNAL_URL=https://faves.example.com` and `FAVORITTER_TRUSTED_PROXIES=<caddy-ip>`.

### Behind Caddy (subpath)

```
example.com {
    handle_path /faves/* {
        reverse_proxy 10.0.0.5:8080
    }
}
```

Set `FAVORITTER_BASE_PATH=/faves` and `FAVORITTER_EXTERNAL_URL=https://example.com/faves`.

### Remote proxy (WireGuard/Tailscale)

Caddy and Favoritter can run on different machines. Set `FAVORITTER_TRUSTED_PROXIES` to the proxy's IP or CIDR (e.g. `100.64.0.0/10` for Tailscale, `10.0.0.0/24` for WireGuard).

## API

The JSON API lives under `/api/v1/`. Authenticate by posting to `/api/v1/auth/login` to get a session cookie, then use it for subsequent requests.

```bash
# Login
curl -c cookies.txt -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"changeme"}'

# List your faves
curl -b cookies.txt http://localhost:8080/api/v1/faves

# Create a fave
curl -b cookies.txt -X POST http://localhost:8080/api/v1/faves \
  -H 'Content-Type: application/json' \
  -d '{"description":"Blade Runner 2049","url":"https://example.com","privacy":"public","tags":["film","sci-fi"]}'

# Export
curl -b cookies.txt http://localhost:8080/api/v1/export/json
```

See the [route list](#routes) for all available endpoints.

## Routes

### Web

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Home page / public feed |
| GET/POST | `/login` | Login |
| GET/POST | `/signup` | Signup (mode-dependent) |
| POST | `/logout` | Logout |
| GET/POST | `/reset-password` | Forced password reset |
| GET | `/faves` | Own faves list |
| GET | `/faves/new` | New fave form |
| POST | `/faves` | Create fave |
| GET | `/faves/{id}` | View fave |
| GET | `/faves/{id}/edit` | Edit fave form |
| POST | `/faves/{id}` | Update fave |
| DELETE | `/faves/{id}` | Delete fave |
| GET | `/tags/search?q=` | Tag autocomplete (HTMX) |
| GET | `/tags/{name}` | Browse by tag |
| GET | `/u/{username}` | Public profile |
| GET/POST | `/settings` | User settings |
| POST | `/settings/avatar` | Upload avatar |
| POST | `/settings/password` | Change password |
| GET | `/export` | Export page |
| GET | `/export/json` | Download JSON |
| GET | `/export/csv` | Download CSV |
| GET/POST | `/import` | Import page |
| GET | `/feed.xml` | Global Atom feed |
| GET | `/u/{username}/feed.xml` | User Atom feed |
| GET | `/tags/{name}/feed.xml` | Tag Atom feed |
| GET | `/admin` | Admin dashboard |
| GET/POST | `/admin/users` | User management |
| GET | `/admin/tags` | Tag management |
| GET/POST | `/admin/signup-requests` | Signup request management |
| GET/POST | `/admin/settings` | Site settings |
| GET | `/health` | Health check |

### API (`/api/v1/`)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/auth/login` | Login, returns session |
| POST | `/api/v1/auth/logout` | Logout |
| GET | `/api/v1/faves` | List own faves |
| POST | `/api/v1/faves` | Create fave |
| GET | `/api/v1/faves/{id}` | Get fave |
| PUT | `/api/v1/faves/{id}` | Update fave |
| DELETE | `/api/v1/faves/{id}` | Delete fave |
| GET | `/api/v1/tags?q=` | Search tags |
| GET | `/api/v1/users/{username}` | Public profile |
| GET | `/api/v1/users/{username}/faves` | User's public faves |
| GET | `/api/v1/export/json` | Export own faves |
| POST | `/api/v1/import` | Import faves |

## Tech Stack

- **Go** (1.22+ stdlib router, `html/template`, `embed`, `log/slog`)
- **SQLite** via [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) (pure Go, no CGO)
- **HTMX** for interactive UI without a JS framework
- **Pico CSS** for semantic HTML styling
- **Argon2id** for password hashing
- **gorilla/feeds** for Atom feed generation

Only 3 external Go dependencies.

## Security

- Argon2id password hashing with timing-attack prevention
- CSRF double-submit cookie pattern (auto-included by HTMX)
- Security headers: CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
- Rate limiting on authentication endpoints
- Image uploads: EXIF metadata stripped, re-encoded, UUID filenames, path traversal protection
- Proxy-aware: trusts `X-Forwarded-For` only from configured proxy CIDRs
- Session cookies: HttpOnly, Secure (from `EXTERNAL_URL` or `X-Forwarded-Proto`), SameSite=Lax

## Development

```bash
# Run in dev mode (live template reload, debug logging)
FAVORITTER_DEV_MODE=true \
FAVORITTER_ADMIN_USERNAME=admin \
FAVORITTER_ADMIN_PASSWORD=dev \
go run ./cmd/favoritter

# Run tests
go test ./...
```

## License

[GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0-or-later)