moby/brewlog
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update documentation for passkey auth

Browse source 
- Replace BREWLOG_ADMIN_USERNAME/PASSWORD with BREWLOG_RP_ID/RP_ORIGIN
- Document first-user bootstrap via one-time registration URL
- Document CLI browser handoff flow for token creation
- Update bootstrap script for new token creation process
- Change default URL references from 127.0.0.1 to localhost
This commit is contained in:
Jon Seager 2026-02-05 11:00:25 +00:00
parent 4bc64dd12f
commit c6b98f81c9
No known key found for this signature in database
2 changed files with 37 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
README.md
View file

@ -20,50 +20,59 @@ B{rew}log ships as one executable. You decide whether it acts as a server or a c
### First-time setup ### First-time setup
The server requires `BREWLOG_OPENROUTER_API_KEY` and `BREWLOG_FOURSQUARE_API_KEY` to be set. On first start, you must also set an admin username and password: The server requires `BREWLOG_RP_ID` and `BREWLOG_RP_ORIGIN` for passkey authentication:
```bash ```bash
BREWLOG_ADMIN_USERNAME="admin" \ BREWLOG_RP_ID="localhost" \
BREWLOG_ADMIN_PASSWORD="your-secure-password" \ BREWLOG_RP_ORIGIN="http://localhost:3000" \
BREWLOG_OPENROUTER_API_KEY="sk-or-..." \ BREWLOG_OPENROUTER_API_KEY="sk-or-..." \
BREWLOG_FOURSQUARE_API_KEY="fsq3..." \ BREWLOG_FOURSQUARE_API_KEY="fsq3..." \
brewlog serve brewlog serve
``` ```
This creates the admin user in the database. On subsequent starts, the admin environment variables are not required. On first start with an empty database, the server prints a one-time registration URL:
```
No users found. Register the first user at:
http://localhost:3000/register/abc123...
This link expires in 1 hour.
```
Open that URL in your browser, enter a display name, and register a passkey. This creates the first user account and signs you in.
> **Important**: The `BREWLOG_RP_ID` is baked into registered passkeys. If you change the domain, all existing passkeys become invalid and you'll need to re-register.
### Authentication ### Authentication
Brewlog supports two authentication methods: Brewlog uses passkey (WebAuthn) authentication. There are no passwords.
1. **Web Frontend**: Session-based authentication via login page 1. **Web Frontend**: Sign in with your passkey to get a session cookie
2. **CLI/API**: Token-based authentication via Bearer tokens 2. **CLI/API**: Bearer tokens created via browser handoff
#### Web Authentication #### Web Authentication
1. Start the server and browse to the frontend 1. Start the server and browse to the frontend
2. Click "Login" in the navigation bar 2. Click "Login" in the navigation bar
3. Sign in with username `admin` and your password 3. Authenticate with your passkey (fingerprint, face, security key, etc.)
4. You're now authenticated and can create/update/delete records 4. You're now authenticated and can create/update/delete records
#### CLI/API Authentication #### CLI/API Authentication
First, create an API token: Token creation uses a browser handoff flow (similar to `gh auth login`):
```bash ```bash
brewlog token create --name "my-cli-token" brewlog token create --name "my-cli-token"
# You will be prompted for username and password. # Opening browser for authentication...
# Alternatively, you can provide them via flags: # If the browser doesn't open, visit this URL:
# brewlog token create --name "my-cli-token" --username admin --password secret #
# http://localhost:3000/login?cli_callback=...
# Username: admin #
# Password: ******** # (authenticate with your passkey in the browser)
# #
# Token created successfully! # Token created successfully!
# Token ID: nye9BDqnLL
# Token Name: my-cli-token # Token Name: my-cli-token
# #
# ⚠ Save this token securely - it will not be shown again: # Save this token securely - it will not be shown again:
# #
# dEadB3efDeadb33fdeadb33F... # dEadB3efDeadb33fdeadb33F...
# #
@ -146,8 +155,8 @@ All configuration is via environment variables or CLI flags. A `.env` file in th
|----------|---------|---------| |----------|---------|---------|
| `BREWLOG_DATABASE_URL` | Database connection string | `sqlite://brewlog.db` | | `BREWLOG_DATABASE_URL` | Database connection string | `sqlite://brewlog.db` |
| `BREWLOG_BIND_ADDRESS` | Server bind address | `127.0.0.1:3000` | | `BREWLOG_BIND_ADDRESS` | Server bind address | `127.0.0.1:3000` |
| `BREWLOG_ADMIN_USERNAME` | Initial admin username | — (required on first run) | | `BREWLOG_RP_ID` | WebAuthn Relying Party ID (your domain, e.g. `localhost` or `brewlog.example.com`) | — (required) |
| `BREWLOG_ADMIN_PASSWORD` | Initial admin password | — (required on first run) | | `BREWLOG_RP_ORIGIN` | WebAuthn Relying Party origin (full URL, e.g. `http://localhost:3000`) | — (required) |
| `BREWLOG_SECURE_COOKIES` | Set to `true` to enable the Secure cookie flag (for HTTPS) | `false` | | `BREWLOG_SECURE_COOKIES` | Set to `true` to enable the Secure cookie flag (for HTTPS) | `false` |
| `RUST_LOG` | Log level filter | `info` | | `RUST_LOG` | Log level filter | `info` |
@ -155,7 +164,7 @@ All configuration is via environment variables or CLI flags. A `.env` file in th
| Variable | Purpose | Default | | Variable | Purpose | Default |
|----------|---------|---------| |----------|---------|---------|
| `BREWLOG_URL` | Server URL for CLI commands | `http://127.0.0.1:3000` | | `BREWLOG_URL` | Server URL for CLI commands | `http://localhost:3000` |
| `BREWLOG_TOKEN` | API token for authenticated CLI operations | — | | `BREWLOG_TOKEN` | API token for authenticated CLI operations | — |
### Integrations ### Integrations

12
scripts/bootstrap-db.sh
View file

@ -3,11 +3,15 @@ set -euo pipefail
cargo build cargo build
BREWLOG_TOKEN="$(./target/debug/brewlog token create --name "bootstrap-token" --username admin --password password | grep -Po "BREWLOG_TOKEN=\K.+$")" # BREWLOG_TOKEN must be set before running this script.
export BREWLOG_TOKEN # To create a token:
# 1. Start the server: ./target/debug/brewlog serve
if [[ -z "$BREWLOG_TOKEN" ]]; then # 2. Register at the URL printed on first start
# 3. Create a token: ./target/debug/brewlog token create --name "bootstrap-token"
# 4. Export the token: export BREWLOG_TOKEN=<token>
if [[ -z "${BREWLOG_TOKEN:-}" ]]; then
echo "Error: BREWLOG_TOKEN environment variable is not set." echo "Error: BREWLOG_TOKEN environment variable is not set."
echo "Create a token first: ./target/debug/brewlog token create --name bootstrap-token"
exit 1 exit 1
fi fi