Caddy Forms-Based Authentication Implementation Plan¶
History. Superseded on 2026-10-22, when #130 was closed. Do not execute it. The 1Password-friendly sign-in now comes from Cloudflare Access, through the G2 tunnel and Access plan. For the current setup see Cloudflare Tunnel. This plan is kept for history only.
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Replace Caddy's browser-native basic_auth challenge for external access with a form-based login that 1Password (and other password managers) can auto-fill.
Motivation: 1Password cannot auto-fill into browser basic-auth pop-ups. External access to tilsit.vip currently uses basic_auth @external_auth_required in the Caddyfile (lines 48–60 at time of writing), which triggers the pop-up. Switching to a form avoids that UX dead-end and matches how every other modern web service handles login.
Architecture: Rebuild the custom Caddy binary with the caddy-security plugin alongside the existing caddy-dns/cloudflare module. caddy-security provides an authentication portal and authorize directive that together deliver a form login, JWT session cookie, and matcher-based bypass for the local network. All configuration stays in the Caddyfile. Single user, bcrypt-hashed password in the Caddyfile, no MFA.
Tech Stack: Caddy (custom build), caddy-security plugin, bcrypt, JWT (HS512), System keychain, LaunchDaemon.
Scope boundaries:
- In scope: form login for
tilsit.vipexternal access; LAN traffic continues to bypass auth; existing TLS strategy (internal PKI + ACME/DNS-01) is unchanged. - Out of scope (deliberately): multi-user, MFA/TOTP, OIDC/OAuth federation, account recovery flows, password rotation UX, admin CLI. If you want any of those later, they slot into caddy-security without rearchitecting.
Known tradeoffs:
caddy-securityreleases lag Caddy core; if youbrew upgrade caddy, the pinned custom build stays, but Caddy security patches require a rebuild with the plugin. You already accept this forcaddy-dns/cloudflare; this adds one more module.- JWT signing-key rotation invalidates all live sessions instantly. Acceptable for single-user home use.
- caddy-security's Caddyfile DSL is verbose and its own thing — expect the configuration diff to be 40–80 lines even for a minimal setup.
File Layout¶
In the repo (source)¶
app-setup/caddy-setup.sh # +keychain check for JWT signing key, +placeholders
app-setup/templates/Caddyfile # -basic_auth, +security {} block, +authenticate/authorize
app-setup/templates/caddy-wrapper.sh # +JWT_SIGNING_KEY injection from keychain
app-setup/templates/com.caddyserver.caddy.plist # no change
docs/apps/caddy-README.md # +section on form auth / caddy-security
docs/apps/caddy-forms-auth-README.md # new operations doc (see Task 8)
tests/ # BATS is optional here (no shell logic changes)
On the server (deployed)¶
/opt/homebrew/bin/caddy # rebuilt with caddy-security + caddy-dns/cloudflare
/opt/homebrew/bin/caddy.pre-forms-auth # backup of current binary (rollback target)
/Users/operator/.config/caddy/Caddyfile # updated config
/usr/local/bin/caddy-wrapper.sh # reads two keychain entries now
System keychain:
service=cloudflare-api-token account=tilsit.vip # existing
service=caddy-jwt-signing-key account=tilsit.vip # new (Task 3)
Bootstrap credentials (1Password + keychain)¶
- New 1Password item:
Caddy external access - tilsit.vip(or reuse an existing one). Contains the user/password the operator will type into the login form. 1Password will fill the form once it exists. - New System keychain entry: JWT signing key, 256+ bits of randomness. Stays on TILSIT, never leaves.
- Existing System keychain entry:
cloudflare-api-token— reused unchanged.
Task 1: Add caddy-security to the custom binary build¶
Rebuild Caddy on the dev machine (not TILSIT) with both the Cloudflare DNS module and caddy-security, then rsync to TILSIT.
Files:
- Modify:
docs/apps/caddy-README.md— extend the "Custom Caddy Build" section with the new download URL - No code changes in this task
Step 1: Build a binary with both modules¶
On the dev machine:
curl -L "https://caddyserver.com/api/download?os=darwin&arch=arm64&p=github.com%2Fcaddy-dns%2Fcloudflare&p=github.com%2Fgreenpau%2Fcaddy-security" \
-o /tmp/caddy-forms
chmod +x /tmp/caddy-forms
/tmp/caddy-forms list-modules | grep -E "cloudflare|security"
Expected: dns.providers.cloudflare AND at least security, http.handlers.authenticate, http.handlers.authorize listed.
Step 2: Stage on TILSIT, keep the old binary as rollback¶
On TILSIT as operator:
sudo cp /opt/homebrew/bin/caddy /opt/homebrew/bin/caddy.pre-forms-auth
sudo cp /tmp/caddy-forms /opt/homebrew/bin/caddy
/opt/homebrew/bin/caddy version
/opt/homebrew/bin/caddy list-modules | grep -E "cloudflare|security"
Do not restart Caddy yet. The deployed Caddyfile still uses basic_auth; the new binary is backward compatible with that directive, so Caddy will keep running — but you want to sequence the binary swap and Caddyfile swap so each can be tested independently.
Step 3: Re-pin in Homebrew on TILSIT¶
The pin prevents TILSIT's brew upgrade caddy from stomping the custom binary we just installed; pinning on the dev machine is irrelevant since we build via the Caddy download API there, not through brew. Run as admin on TILSIT (Homebrew refuses root):
/opt/homebrew/bin/brew unpin caddy || true
/opt/homebrew/bin/brew pin caddy
/opt/homebrew/bin/brew list --pinned | grep caddy
Step 4: Commit the doc changes¶
git add docs/apps/caddy-README.md
git commit -m "docs(caddy): document custom build with caddy-security module"
Task 2: Generate and install the JWT signing key¶
The session cookie is a signed JWT. We need a long-lived secret for HS512 signing.
Files: none (keychain + 1Password only)
Step 1: Generate 64 random bytes, base64-encoded¶
On the dev machine:
Step 2: Stash in 1Password for recovery¶
Create 1Password item Caddy JWT signing key - tilsit.vip, Password field = the base64 string. You'll need this if you ever reinstall TILSIT.
Step 3: Install into System keychain on TILSIT¶
From the dev machine. Use the admin account, not operator — non-interactive SSH as operator cannot run sudo without a TTY and the System keychain requires root:
ssh -t admin@your-server.local "sudo security add-generic-password -U \
-s 'caddy-jwt-signing-key' \
-a 'tilsit.vip' \
-w '${JWT_KEY}' \
/Library/Keychains/System.keychain"
unset JWT_KEY
Step 4: Verify retrieval¶
On TILSIT as admin:
sudo security find-generic-password -s caddy-jwt-signing-key -a tilsit.vip \
/Library/Keychains/System.keychain -w | wc -c
Expected: a single line, same length as ${#JWT_KEY} + 1 (newline).
Step 5: No commit — this task is keychain-only¶
Task 3: Teach caddy-wrapper.sh to inject JWT_SIGNING_KEY¶
Same pattern as CF_API_TOKEN.
Files:
- Modify:
app-setup/templates/caddy-wrapper.sh
Step 1: Extend the wrapper¶
Current wrapper reads one key. Change to read two:
#!/usr/bin/env bash
# caddy-wrapper.sh — reads CF_API_TOKEN + JWT_SIGNING_KEY from System keychain,
# then exec's Caddy. Run as root via LaunchDaemon.
set -euo pipefail
keychain_read() {
local service="$1" account="$2"
security find-generic-password -s "${service}" -a "${account}" -w \
/Library/Keychains/System.keychain
}
CF_API_TOKEN=$(keychain_read "cloudflare-api-token" "__EXTERNAL_HOSTNAME__") || {
echo "ERROR: cloudflare-api-token not found in System keychain" >&2
exit 1
}
JWT_SIGNING_KEY=$(keychain_read "caddy-jwt-signing-key" "__EXTERNAL_HOSTNAME__") || {
echo "ERROR: caddy-jwt-signing-key not found in System keychain" >&2
exit 1
}
export CF_API_TOKEN JWT_SIGNING_KEY
exec /opt/homebrew/bin/caddy run \
--config /Users/__OPERATOR_USERNAME__/.config/caddy/Caddyfile \
--adapter caddyfile
Step 2: shellcheck + shfmt¶
shellcheck --severity=warning --exclude=SC2312 app-setup/templates/caddy-wrapper.sh
shfmt -d -i 2 -ci -bn app-setup/templates/caddy-wrapper.sh
Both should exit 0.
Step 3: Commit¶
git add app-setup/templates/caddy-wrapper.sh
git commit -m "feat(caddy): inject JWT_SIGNING_KEY alongside CF_API_TOKEN"
Task 4: Pick and hash the login password¶
Files: none (1Password + local hash)
Step 1: Choose a password and stash in 1Password¶
Create a strong password. Save to 1Password as Caddy external access - tilsit.vip (field: password). This is what you'll type/autofill into the form.
Step 2: Generate the bcrypt hash¶
(Or on any machine with Caddy, caddy hash-password --plaintext '<your-password>'.)
Expected output: $2a$14$... string. Save that string for Task 5. Do not commit it.
Step 3: Add BASICAUTH_HASH replacement to config.conf (temporary holding spot)¶
You already keep BASICAUTH_HASH in config/config.conf (gitignored) for the old basic_auth directive. The new form-auth reuses the same hash format and the same config var — no new placeholder needed. Just update the value:
Task 5: Rewrite the Caddyfile to use form auth¶
This is the biggest single change. The common_config snippet gets a new authentication portal and the external block swaps basic_auth for authorize.
Files:
- Modify:
app-setup/templates/Caddyfile - Modify:
app-setup/caddy-setup.sh(validate the new JWT env var is set before substitution; add acaddy validatedummy value forJWT_SIGNING_KEY)
Step 1: Add the security global block¶
Near the top of the Caddyfile, alongside the existing pki block inside the global { … }:
{
pki {
ca local {
name "Home Server CA"
intermediate_lifetime 90d
}
}
security {
local identity store localauth {
realm local
path /Users/__OPERATOR_USERNAME__/.config/caddy/users.json
}
authentication portal authp {
crypto default token lifetime 86400
crypto key sign-verify {$JWT_SIGNING_KEY}
enable identity store localauth
cookie domain __EXTERNAL_HOSTNAME__
cookie lifetime 86400
cookie samesite lax
ui {
links {
"Dashboard" / icon "las la-home"
"Sign Out" /auth/logout icon "las la-sign-out-alt"
}
}
transform user {
match origin local
action add role authp/user
}
}
authorization policy external_policy {
set auth url https://__EXTERNAL_HOSTNAME__/auth/
crypto key verify {$JWT_SIGNING_KEY}
allow roles authp/user
}
}
}
Step 2: Replace basic_auth with authenticate + authorize¶
Inside (common_config), delete the existing basic_auth @external_auth_required { ... } block and replace with:
# Authentication portal — serves the login form at /auth/
route /auth* {
authenticate with authp
}
# Authorization gate — protects everything else on external access.
# @local_network already bypasses the match; @external_auth_required is
# preserved as the "needs auth" matcher.
route @external_auth_required {
authorize with external_policy
}
Leave the @local_network / @external_auth_required matchers as they are (they still gate on remote IP + host).
Step 3: Create users.json template¶
caddy-security's local store wants a JSON file. Create it as a template alongside Caddyfile:
app-setup/templates/caddy-users.json:
{
"users": [
{
"id": "__OPERATOR_USERNAME__",
"username": "__BASICAUTH_USERNAME__",
"password": "__BASICAUTH_HASH__",
"email": "__MONITORING_EMAIL__",
"roles": ["authp/user"],
"enabled": true
}
]
}
Three edits to caddy-setup.sh, placement matters:
-
Near the top of the script, where the other config vars are read (around caddy-setup.sh:21–27), add:
This must come before the preflight check added in Task 6 Step 1.
-
Inside the
substitute_template()function body (caddy-setup.sh:57–69), add one more-eline to the sed chain — insert it immediately before the final"${src}" >"${dst}"line so the backslash continuations stay valid: -
Between the Caddyfile deploy and the
caddy validateblock (after caddy-setup.sh:114, before line ~180), add the users.json deploy. This ordering is load-bearing: caddy-security'slocal identity storedirective references theusers.jsonpath at validate time, so the file must exist beforecaddy validateruns.
Mode 0600 is mandatory — the file contains the bcrypt password hash.
Step 4: Commit¶
git add app-setup/templates/Caddyfile app-setup/templates/caddy-users.json app-setup/caddy-setup.sh
git commit -m "feat(caddy): replace basic_auth with caddy-security form-based portal"
Task 6: Update caddy-setup.sh to require the new token¶
Add preflight checks mirroring the existing Cloudflare token check.
Files:
- Modify:
app-setup/caddy-setup.sh
Step 1: Add preflight check for MONITORING_EMAIL¶
The users.json template (Task 5 Step 3) uses __MONITORING_EMAIL__, so the value must be non-empty before substitution or the deployed file would contain a literal placeholder.
if [[ -z "${MONITORING_EMAIL:-}" ]]; then
echo "❌ MONITORING_EMAIL is required (used for caddy-security user identity)"
echo " Set MONITORING_EMAIL in config/config.conf"
exit 1
fi
Step 2: Add keychain check¶
Near the existing keychain-entry check for cloudflare-api-token, add:
if ! security find-generic-password \
-s "caddy-jwt-signing-key" \
-a "${EXTERNAL_HOSTNAME}" \
/Library/Keychains/System.keychain >/dev/null 2>&1; then
echo "❌ Keychain entry not found:"
echo " service=caddy-jwt-signing-key account=${EXTERNAL_HOSTNAME}"
echo
echo " Generate and install with:"
echo " JWT=\$(openssl rand -base64 64 | tr -d \\\\n)"
echo " sudo security add-generic-password -U \\"
echo " -s 'caddy-jwt-signing-key' -a '${EXTERNAL_HOSTNAME}' \\"
echo " -w \"\${JWT}\" /Library/Keychains/System.keychain"
exit 1
fi
Step 3: Update the caddy validate invocation with a dummy JWT key¶
The existing DUMMY_TOKEN pattern lets caddy validate run without real credentials. Extend it:
DUMMY_TOKEN="dummy0token0for0validation0only000000000"
DUMMY_JWT="dummy0jwt0signing0key0for0validation0only00000000000000000000000"
if HOSTNAME="${HOSTNAME}" \
CF_API_TOKEN="${DUMMY_TOKEN}" \
JWT_SIGNING_KEY="${DUMMY_JWT}" \
"${CADDY_BIN}" validate --config "${DEPLOY_CONFIG_DIR}/Caddyfile" 2>&1; then
echo "✓ Configuration valid"
else
echo "❌ Configuration validation failed"
exit 1
fi
Step 4: shellcheck + shfmt¶
shellcheck --severity=warning --exclude=SC2312 app-setup/caddy-setup.sh
shfmt -d -i 2 -ci -bn app-setup/caddy-setup.sh
Step 5: Commit¶
git add app-setup/caddy-setup.sh
git commit -m "feat(caddy-setup): require JWT signing key + email before deploy"
Task 7: Deploy, test, document rollback¶
This is the cutover. Do it when you have 20 minutes of uninterrupted keyboard time — the external site is briefly unreachable during the restart.
Step 1: Fresh Caddy binary already on TILSIT (from Task 1)¶
Verify:
/opt/homebrew/bin/caddy list-modules | grep -E "security|cloudflare" | wc -l
# expect ≥ 2
ls -l /opt/homebrew/bin/caddy.pre-forms-auth # rollback binary exists
Step 2: Back up the current deployed Caddyfile¶
Do this before running caddy-setup.sh in the next step — otherwise the rollback in Step 7 has nothing to restore from.
sudo -iu operator cp \
~/.config/caddy/Caddyfile \
~/.config/caddy/Caddyfile.pre-forms-auth.$(date +%Y%m%d)
ls -l /Users/operator/.config/caddy/Caddyfile.pre-forms-auth.*
Expected: one backup file listed with today's date.
Step 3: Deploy the new Caddyfile¶
On TILSIT, from the repo:
Expected (string match exactly what caddy-setup.sh emits):
✓ Copied Caddyfile to /Users/operator/.config/caddy/✓ Copied users.json to /Users/operator/.config/caddy/ (mode 600)✓ Configuration valid
Step 4: Restart Caddy¶
sudo launchctl kickstart -k system/com.caddyserver.caddy
sleep 5
sudo launchctl print system/com.caddyserver.caddy | grep -E "state|last exit code"
Expected: state = running, last exit code = 0.
Step 5: Functional tests¶
Run the external-path tests from the dev machine (not from TILSIT). TILSIT's own source IP matches the @local_network matcher, so the curl would hit the LAN bypass and every assertion would pass for the wrong reason. The LAN test is the only one that belongs on TILSIT itself.
On TILSIT — verify LAN bypass still works:
On the dev machine (off the TILSIT LAN) — verify the form-auth path:
# Unauthenticated hit redirects to /auth/
curl -ksI https://tilsit.vip/ | grep -iE "^HTTP|^location"
# expect HTTP/2 302 + location: /auth/
# /auth/ serves a login form (not a 401 with basic-auth realm)
curl -ks https://tilsit.vip/auth/ | grep -qi '<form' && echo "form present"
# No WWW-Authenticate header (would indicate basic_auth regression)
curl -ksI https://tilsit.vip/ | grep -qi "^www-authenticate" \
&& echo "BUG: still sending basic_auth" \
|| echo "basic_auth gone"
If the dev machine happens to share the 192.168.21.0/24 subnet with TILSIT, run the external tests from cellular (phone hotspot) or any VPN tunneling through a non-LAN address instead.
Step 6: Browser test¶
From a device off the LAN (cellular, VPN off):
- Visit
https://tilsit.vip/ - Expect redirect to
https://tilsit.vip/auth/ - Expect 1Password to offer to fill the saved credential
- Submit → expect redirect back to
/with a session cookie - Navigate to
/transmission/— expect no re-prompt - Visit
/auth/logout→ expect session cleared
If any step fails, proceed to rollback.
Step 7: Rollback plan (if anything is broken)¶
Relies on the backups created in Task 1 Step 2 (/opt/homebrew/bin/caddy.pre-forms-auth) and Task 7 Step 2 (~/.config/caddy/Caddyfile.pre-forms-auth.YYYYMMDD). Both must exist before you hit this step.
The Caddyfile restore uses ls -t ... | head -1 rather than $(date +%Y%m%d) — if the cutover rolls past midnight, a fresh date call would reconstruct the wrong filename and cp would fail exactly when you need it. Picking the most-recent backup works regardless of the clock and also DTRT when multiple backups exist from retried cutovers.
sudo cp /opt/homebrew/bin/caddy.pre-forms-auth /opt/homebrew/bin/caddy
# Confirm what you're about to restore BEFORE copying
ls -t /Users/operator/.config/caddy/Caddyfile.pre-forms-auth.*
sudo -iu operator bash -c '
latest=$(ls -t ~/.config/caddy/Caddyfile.pre-forms-auth.* | head -1)
[[ -f "${latest}" ]] || { echo "no backup found" >&2; exit 1; }
cp "${latest}" ~/.config/caddy/Caddyfile
'
sudo launchctl kickstart -k system/com.caddyserver.caddy
Step 8: Announce completion in commit¶
git add -A # only the docs/templates that changed, no secrets
git commit -m "feat(caddy): cut over to caddy-security form auth"
Task 8: Write the operations doc¶
Add a new service-README alongside docs/apps/caddy-README.md.
Files:
- Create:
docs/apps/caddy-forms-auth-README.md - Modify:
CLAUDE.md— add a bullet to the "Service-Specific Documentation" section pointing at the new README
Step 1: Topics to cover in caddy-forms-auth-README.md¶
- Where the login form lives (
/auth/) and what a session cookie looks like - How to rotate the JWT signing key (and the session-invalidation implication)
- How to change the password (regenerate bcrypt hash, edit
users.jsonin place,kickstartCaddy) - Why
BASICAUTH_USERNAME/BASICAUTH_HASHkept their names even though basic-auth is gone (deliberate — avoids a config migration) - How to temporarily disable auth for debugging (comment the
authorizeline, restart Caddy, never leave it that way) - Rollback procedure from Task 7 Step 7
Step 2: Add CLAUDE.md entry¶
Under the Caddy entry, mention the auth model is form-based via caddy-security and point at the new README. Keep it to two or three lines.
Step 3: markdownlint¶
Step 4: Commit¶
git add docs/apps/caddy-forms-auth-README.md CLAUDE.md
git commit -m "docs(caddy): document form-auth operations and rollback"
Effort Summary¶
| Task | Wall-clock |
|---|---|
| 1. Custom Caddy build | 30–60 min |
| 2. JWT signing key into keychain | 15 min |
3. Update caddy-wrapper.sh |
30 min |
| 4. Pick + hash password | 10 min |
| 5. Caddyfile rewrite + users.json | 2 hours |
6. caddy-setup.sh preflight |
30 min |
| 7. Deploy, test, verify 1Password flow | 30–60 min |
| 8. Docs | 45 min |
| Total | ~5–6 hours (realistic one-morning project) |
Risks Recap¶
- Browser-level basic_auth credential caching. Once the new Caddyfile is live, browsers that cached the old basic-auth credential for
tilsit.vipmay keep sendingAuthorization: Basicheaders in addition to following the redirect. caddy-security ignores them, but it can make the "first login after cutover" confusing. Tell any human user to close/reopen the browser after cutover. caddy-securityCaddyfile DSL drift. The plugin's syntax has changed across releases. Verify against the exact tag ofcaddy-securitythatgreenpau/caddy-securitylatest resolves to when you execute Task 1 — pin to that tag in the README if the?p=download-API URL supports it.enable identity store localauthmay need to beenable identity_store localauth(underscore vs space) depending on plugin version. Ifcaddy validaterejects the snippet in Task 5 Step 1, this is the first thing to try.users.jsonis sensitive. Mode must be 0600.caddy-setup.shenforces this, but verify after every redeploy:ls -l ~/.config/caddy/users.json.- Keychain-access symmetry. If you ever migrate TILSIT to a new machine, both
cloudflare-api-tokenANDcaddy-jwt-signing-keymust be reinstalled. Add that to whatever disaster-recovery doc you maintain.
Out-of-Scope Follow-Ups (park these, don't bundle)¶
- MFA via TOTP.
caddy-securitysupports it; adds ~1 hour. - OIDC for remote family members. Adds
google/githubas identity stores; deletesusers.json. ~2 hours. - Session logout UI. Currently
/auth/logoutworks via direct URL; adding a dashboard button is UI-only work. - Remember-me cookie beyond 24 hours. Lifetime is tunable in
token lifetimeandcookie lifetime; trivial but has security implications. - Per-path authorization. e.g. allow
/healthunauthenticated even externally. caddy-security's policies support this; add a secondauthorization policyfor the exempted paths.