Skip to content

Add isolated local password authentication - #15

Merged
jzhao234 merged 2 commits into
mainfrom
feat/local-password-auth
Sep 9, 2026
Merged

jzhao234 merged 2 commits into
mainfrom
feat/local-password-auth

Conversation

@jzhao234

@jzhao234 jzhao234 commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

TLDR

Explorer can now select either the existing external magic-link verifier or a deployment-local username/password provider. Local mode uses Argon2id credentials, revocable opaque sessions, secure host-only cookies, and operator-assisted account recovery without changing existing external-auth deployments.

Motivation

Some Explorer installations need accounts isolated from the surrounding application fleet while keeping one consistent, reviewable authentication implementation. Previously, Explorer could only consume the external magic-link cookie.

Fix

  • Add a versioned SQLite account/session store with Argon2id hashing, random 256-bit opaque session tokens, 60-minute idle and 12-hour absolute expiration, rate limits, audit events, and immediate revocation.
  • Add local login, mandatory temporary-password replacement, CSRF-protected password change/logout, fixed post-login destinations, generic login errors, and a deny-by-default route gate.
  • Prompt for admin-supplied temporary passwords through hidden terminal input and never print or write them.
  • Preserve the external Ed25519 magic-link provider as the default for existing deployments and keep provider cookies isolated.
  • Add operator user lifecycle commands, protected systemd state storage, bootstrap/update support, and database backup/restore guidance.
  • Require HTTPS for the host-only __Host-explorer_session cookie and fail local startup with an empty/default session secret.

Tests

  • 91 passed.venv/bin/python -m pytest -q
  • All checks passed.venv/bin/ruff check app tests
  • 16 files already formatted.venv/bin/ruff format --check app tests
  • Passed — bash -n deploy/explorer-cli scripts/bootstrap.sh scripts/update.sh scripts/provision.sh
  • Passed — git diff --check
  • No leaks found — gitleaks git --staged --redact --no-banner .
  • Fresh environment used the current pinned FastAPI, Starlette, cryptography, and Argon2 dependencies.

Checklist

  • ruff check app tests && ruff format --check app tests pass
  • python -m pytest -q passes, with no AWS account or network needed
  • Fixtures stay synthetic (.example addresses; no real mail)
  • Docs updated where behaviour changed
  • New source files carry the SPDX header
  • No secrets, real customer data, or internal hostnames in the diff

Screenshots

Not included. The two small authentication templates reuse Explorer's existing design system; their rendered forms, cookie headers, redirects, and failure states are covered by endpoint tests.

Comment thread app/auth_admin.py Fixed
Comment thread app/auth_admin.py Fixed
Comment thread app/main.py Fixed
@jzhao234
jzhao234 force-pushed the feat/local-password-auth branch 2 times, most recently from f50eac4 to 0ab0bb9 Compare September 8, 2026 20:34
Comment thread app/auth_admin.py Fixed
TLDR

Explorer can now select either the existing external magic-link verifier or a deployment-local username/password provider. Local mode uses Argon2id credentials, revocable opaque sessions, secure host-only cookies, and operator-assisted account recovery without changing existing deployments.

Motivation

Some Explorer installations need accounts isolated from the surrounding application fleet while keeping one consistent and reviewable authentication implementation.

Fix

- Add a versioned SQLite account/session store with Argon2id hashing, 256-bit opaque session tokens, idle and absolute expiration, rate limits, audit events, and immediate revocation.
- Add local login, mandatory temporary-password replacement, CSRF-protected password change/logout, fixed post-login destinations, and a deny-by-default route gate.
- Prompt for admin-supplied temporary passwords through hidden terminal input and never print or write them.
- Preserve the external Ed25519 magic-link provider as the default for existing deployments and keep provider cookies isolated.
- Add operator user lifecycle commands, protected systemd state storage, bootstrap/update support, and database backup/restore guidance.

Tests

- .venv/bin/python -m pytest -q (91 passed)
- .venv/bin/ruff check app tests
- .venv/bin/ruff format --check app tests
- bash -n deploy/explorer-cli scripts/bootstrap.sh scripts/update.sh scripts/provision.sh
- git diff --check
- gitleaks git --staged --redact --no-banner .
@jzhao234
jzhao234 force-pushed the feat/local-password-auth branch from 0ab0bb9 to a06e7a4 Compare September 8, 2026 20:43
@jzhao234
jzhao234 merged commit 6725079 into main Sep 9, 2026
4 checks passed
@jzhao234
jzhao234 deleted the feat/local-password-auth branch September 9, 2026 16:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants