From c6b98f81c942174393d1528f96a493c6b4ff9d65 Mon Sep 17 00:00:00 2001 From: Jon Seager Date: Thu, 5 Feb 2026 11:00:25 +0000 Subject: [PATCH] docs: update documentation for passkey auth - 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 --- README.md | 49 ++++++++++++++++++++++++----------------- scripts/bootstrap-db.sh | 12 ++++++---- 2 files changed, 37 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a6928bb..3a88f92 100644 --- a/README.md +++ b/README.md @@ -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 -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 -BREWLOG_ADMIN_USERNAME="admin" \ -BREWLOG_ADMIN_PASSWORD="your-secure-password" \ +BREWLOG_RP_ID="localhost" \ +BREWLOG_RP_ORIGIN="http://localhost:3000" \ BREWLOG_OPENROUTER_API_KEY="sk-or-..." \ BREWLOG_FOURSQUARE_API_KEY="fsq3..." \ 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 -Brewlog supports two authentication methods: +Brewlog uses passkey (WebAuthn) authentication. There are no passwords. -1. **Web Frontend**: Session-based authentication via login page -2. **CLI/API**: Token-based authentication via Bearer tokens +1. **Web Frontend**: Sign in with your passkey to get a session cookie +2. **CLI/API**: Bearer tokens created via browser handoff #### Web Authentication 1. Start the server and browse to the frontend 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 #### CLI/API Authentication -First, create an API token: +Token creation uses a browser handoff flow (similar to `gh auth login`): ```bash brewlog token create --name "my-cli-token" -# You will be prompted for username and password. -# Alternatively, you can provide them via flags: -# brewlog token create --name "my-cli-token" --username admin --password secret - -# Username: admin -# Password: ******** +# Opening browser for authentication... +# If the browser doesn't open, visit this URL: +# +# http://localhost:3000/login?cli_callback=... +# +# (authenticate with your passkey in the browser) # # Token created successfully! -# Token ID: nye9BDqnLL # 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... # @@ -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_BIND_ADDRESS` | Server bind address | `127.0.0.1:3000` | -| `BREWLOG_ADMIN_USERNAME` | Initial admin username | — (required on first run) | -| `BREWLOG_ADMIN_PASSWORD` | Initial admin password | — (required on first run) | +| `BREWLOG_RP_ID` | WebAuthn Relying Party ID (your domain, e.g. `localhost` or `brewlog.example.com`) | — (required) | +| `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` | | `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 | |----------|---------|---------| -| `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 | — | ### Integrations diff --git a/scripts/bootstrap-db.sh b/scripts/bootstrap-db.sh index ce07269..36a2343 100755 --- a/scripts/bootstrap-db.sh +++ b/scripts/bootstrap-db.sh @@ -3,11 +3,15 @@ set -euo pipefail cargo build -BREWLOG_TOKEN="$(./target/debug/brewlog token create --name "bootstrap-token" --username admin --password password | grep -Po "BREWLOG_TOKEN=\K.+$")" -export BREWLOG_TOKEN - -if [[ -z "$BREWLOG_TOKEN" ]]; then +# BREWLOG_TOKEN must be set before running this script. +# To create a token: +# 1. Start the server: ./target/debug/brewlog serve +# 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= +if [[ -z "${BREWLOG_TOKEN:-}" ]]; then echo "Error: BREWLOG_TOKEN environment variable is not set." + echo "Create a token first: ./target/debug/brewlog token create --name bootstrap-token" exit 1 fi