Merge branch 'hopper-krcsslej-init-guard-auth'

apps/health/tests/conftest.py

···
 
 from __future__ import annotations
 
+import json
+
 import pytest
 
 
···
     ):
         journal = tmp_path / "journal"
         journal.mkdir(exist_ok=True)
+
+        config_dir = journal / "config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_file = config_dir / "journal.json"
+        config_file.write_text(
+            json.dumps(
+                {
+                    "convey": {"trust_localhost": True},
+                    "setup": {"completed_at": 1700000000000},
+                },
+                indent=2,
+            )
+        )
 
         # Create sample log file
         log_file = journal / log_path

apps/observer/tests/conftest.py

···
 
 from __future__ import annotations
 
+import json
+
 import pytest
 
 
···
     def _create():
         journal = tmp_path / "journal"
         journal.mkdir()
+
+        config_dir = journal / "config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_file = config_dir / "journal.json"
+        config_file.write_text(
+            json.dumps(
+                {
+                    "convey": {"trust_localhost": True},
+                    "setup": {"completed_at": 1700000000000},
+                },
+                indent=2,
+            )
+        )
 
         # Set environment
         monkeypatch.setenv("_SOLSTONE_JOURNAL_OVERRIDE", str(journal))

convey/__init__.py

···
     os.chmod(config_path, 0o600)
 
 
+def _migrate_setup_completed() -> None:
+    """Infer setup.completed_at and set trust_localhost for existing installs."""
+    from think.utils import get_config, get_journal
+
+    config = get_config()
+
+    if not config.get("convey", {}).get("password_hash"):
+        return
+    if config.get("setup", {}).get("completed_at"):
+        return
+
+    from think.utils import now_ms
+
+    config.setdefault("setup", {})["completed_at"] = now_ms()
+    config.setdefault("convey", {})["trust_localhost"] = True
+
+    config_path = Path(get_journal()) / "config" / "journal.json"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    os.chmod(config_path, 0o600)
+
+
 def create_app(journal: str = "") -> Flask:
     """Create and configure the Convey Flask application."""
     app = Flask(
···
 
     app.secret_key = _get_or_create_secret()
     _migrate_password_hash()
+    _migrate_setup_completed()
     app.config["PERMANENT_SESSION_LIFETIME"] = timedelta(days=30)
 
     # Register root blueprint (login, logout, /, favicon)

convey/root.py

···
         return ""
 
 
+def _is_setup_complete() -> bool:
+    """Check if initial setup has been completed."""
+    try:
+        config = get_config()
+        return bool(config.get("setup", {}).get("completed_at"))
+    except Exception:
+        return False
+
+
+def _check_basic_auth() -> bool:
+    """Check Basic Auth credentials against stored password hash."""
+    auth = request.authorization
+    if not auth or auth.type != "basic":
+        return False
+    password_hash = _get_password_hash()
+    if not password_hash:
+        return False
+    return check_password_hash(password_hash, auth.password or "")
+
+
 def _save_config_section(section: str, data: dict) -> dict:
     """Merge data into a config section and write back to journal.json."""
     config = get_config()
···
     }:
         return None
 
-    # Auto-bypass for localhost requests WITHOUT proxy headers
-    remote_addr = request.remote_addr
-    is_localhost = remote_addr in ("127.0.0.1", "::1", "localhost")
+    # Session cookie
+    if session.get("logged_in"):
+        return None
+
+    # Basic Auth (per-request, no session creation)
+    if _check_basic_auth():
+        return None
 
-    # Detect proxy headers that might indicate forwarded external request
-    proxy_headers = (
-        request.headers.get("X-Forwarded-For")
-        or request.headers.get("X-Real-IP")
-        or request.headers.get("X-Forwarded-Host")
-    )
+    # Check setup state
+    setup_complete = _is_setup_complete()
 
-    if is_localhost and not proxy_headers:
-        # Genuine localhost request - auto-bypass
-        return None
+    # Opt-in localhost bypass (requires completed setup + trust_localhost flag)
+    if setup_complete:
+        config = get_config()
+        if config.get("convey", {}).get("trust_localhost", False):
+            remote_addr = request.remote_addr
+            is_localhost = remote_addr in ("127.0.0.1", "::1", "localhost")
+            proxy_headers = (
+                request.headers.get("X-Forwarded-For")
+                or request.headers.get("X-Real-IP")
+                or request.headers.get("X-Forwarded-Host")
+            )
+            if is_localhost and not proxy_headers:
+                return None
 
-    # Otherwise require session authentication
-    if not session.get("logged_in"):
-        if not _get_password_hash():
-            return redirect(url_for("root.init"))
-        return redirect(url_for("root.login"))
+    # Not authenticated — redirect based on setup state
+    if not setup_complete:
+        return redirect(url_for("root.init"))
+    return redirect(url_for("root.login"))
 
 
 @bp.route("/login", methods=["GET", "POST"])
···
 
 @bp.route("/init")
 def init() -> Any:
-    if _get_password_hash():
+    if _is_setup_complete():
         return redirect(url_for("root.index"))
 
     config_path = str(Path(get_journal()) / "config" / "journal.json")
     repo_path = str(Path(__file__).resolve().parent.parent)
-    return render_template("init.html", config_path=config_path, repo_path=repo_path)
+    has_password = bool(_get_password_hash())
+    return render_template(
+        "init.html",
+        config_path=config_path,
+        repo_path=repo_path,
+        has_password=has_password,
+    )
 
 
 @bp.route("/init/password", methods=["POST"])

convey/screenshot.py

···
     script: str | None = None,
     facet: str | None = None,
     delay: int = 0,
+    password: str | None = None,
 ) -> None:
     """
     Capture screenshot of a Convey view.
···
         script: Optional JavaScript to execute before taking screenshot
         facet: Optional facet to select (use "all" for all-facet mode)
         delay: Milliseconds to wait after page load before screenshot (default: 0)
+        password: Optional password for Basic Auth
     """
     # Ensure route has leading slash
     if not route.startswith("/"):
···
 
     with sync_playwright() as p:
         browser = p.chromium.launch()
-        context = browser.new_context(viewport={"width": width, "height": height})
+        context_kwargs: dict = {"viewport": {"width": width, "height": height}}
+        if password:
+            context_kwargs["http_credentials"] = {"username": "", "password": password}
+        context = browser.new_context(**context_kwargs)
 
         # Set facet selection cookie if specified
         if facet:
···
         default=None,
         help="Delay in ms after page load (default: 500 if route has #fragment, else 0)",
     )
+    parser.add_argument(
+        "--password",
+        help="Password for Basic Auth",
+    )
 
     args = setup_cli(parser)
 
···
         script=args.script,
         facet=args.facet,
         delay=args.delay,
+        password=args.password,
     )
 
 

convey/templates/init.html

···
         if (data.success && data.redirect) window.location.href = data.redirect;
       } catch (err) {}
     }
+
+    {% if has_password %}
+    document.addEventListener('DOMContentLoaded', function() {
+      const pwField = document.getElementById('password');
+      pwField.value = '\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022';
+      pwField.disabled = true;
+      const toggle = document.getElementById('toggle-password');
+      if (toggle) toggle.style.display = 'none';
+      unlockSections();
+    });
+    {% endif %}
   </script>
 </body>
 </html>

tests/baselines/api/settings/config.json

···
     "proposal_count": 0
   },
   "convey": {
-    "has_password": true
+    "has_password": true,
+    "trust_localhost": true
   },
   "describe": {
     "redact": [
···
     "OPENAI_API_KEY": false,
     "PLAUD_ACCESS_TOKEN": false,
     "REVAI_ACCESS_TOKEN": false
+  },
+  "setup": {
+    "completed_at": 1700000000000
   },
   "transcribe": {
     "backend": "whisper",

tests/fixtures/journal/config/journal.json

···
   },
   "convey": {
     "password_hash": "scrypt:32768:8:1$ceTJLGRcxYTqVQ4n$74a88b364046ab7ca627df875f27b1fb50994d4311ff8c86393bd7d32eaac303c81f165e79a99164931457846b4e702ac6cb38b877871cb4fadf1f70937bbfba",
-    "secret": "test-fixture-secret-do-not-use-in-production"
+    "secret": "test-fixture-secret-do-not-use-in-production",
+    "trust_localhost": true
+  },
+  "setup": {
+    "completed_at": 1700000000000
   },
   "transcribe": {
     "backend": "whisper",

tests/test_init.py

···
+import base64
 import json
 
 import pytest
···
     config = _read_config(journal_dir)
     config["convey"].pop("password_hash", None)
     config["convey"].pop("password", None)
+    config["convey"].pop("trust_localhost", None)
+    config.pop("setup", None)
     (journal_dir / "config" / "journal.json").write_text(json.dumps(config, indent=2))
 
 
···
         )
         resp = fresh_client.get("/init")
         assert resp.status_code == 302
+
+
+class TestLocalhostBypass:
+    """Tests for the opt-in trust_localhost bypass."""
+
+    def test_localhost_fresh_install_redirects_to_init(self, fresh_client):
+        """Plain localhost with no config → redirect to /init."""
+        resp = fresh_client.get("/")
+        assert resp.status_code == 302
+        assert "/init" in resp.headers["Location"]
+
+    def test_localhost_trust_bypass(self, journal_copy):
+        """Localhost + trust_localhost + setup.completed_at → pass through."""
+        config = _read_config(journal_copy)
+        config["convey"]["trust_localhost"] = True
+        config["setup"] = {"completed_at": 1700000000000}
+        (journal_copy / "config" / "journal.json").write_text(
+            json.dumps(config, indent=2)
+        )
+        app = create_app(str(journal_copy))
+        app.config["TESTING"] = True
+        client = app.test_client()
+        resp = client.get("/")
+        assert resp.status_code == 302
+        # Should redirect to home app, not login or init
+        assert "/login" not in resp.headers["Location"]
+        assert "/init" not in resp.headers["Location"]
+
+    def test_localhost_trust_without_setup_redirects_to_init(self, journal_copy):
+        """trust_localhost set but no setup.completed_at → redirect to /init."""
+        config = _read_config(journal_copy)
+        config["convey"]["trust_localhost"] = True
+        config.pop("setup", None)
+        config["convey"].pop("password_hash", None)
+        (journal_copy / "config" / "journal.json").write_text(
+            json.dumps(config, indent=2)
+        )
+        app = create_app(str(journal_copy))
+        app.config["TESTING"] = True
+        client = app.test_client()
+        resp = client.get("/")
+        assert resp.status_code == 302
+        assert "/init" in resp.headers["Location"]
+
+    def test_localhost_no_trust_redirects_to_login(self, journal_copy):
+        """Localhost + setup.completed_at but no trust_localhost → redirect to /login."""
+        config = _read_config(journal_copy)
+        config["convey"].pop("trust_localhost", None)
+        config["setup"] = {"completed_at": 1700000000000}
+        (journal_copy / "config" / "journal.json").write_text(
+            json.dumps(config, indent=2)
+        )
+        app = create_app(str(journal_copy))
+        app.config["TESTING"] = True
+        client = app.test_client()
+        resp = client.get("/")
+        assert resp.status_code == 302
+        assert "/login" in resp.headers["Location"]
+
+    def test_proxy_header_defeats_trust_localhost(self, configured_client):
+        """Proxy headers prevent trust_localhost bypass."""
+        resp = configured_client.get("/", headers={"X-Forwarded-For": "1.2.3.4"})
+        assert resp.status_code == 302
+        assert "/login" in resp.headers["Location"]
+
+
+class TestBasicAuth:
+    """Tests for Basic Auth support."""
+
+    def test_basic_auth_correct_password(self, configured_client):
+        """Basic Auth with correct password → authenticated."""
+        creds = base64.b64encode(b":test123").decode()
+        resp = configured_client.get(
+            "/",
+            headers={
+                "Authorization": f"Basic {creds}",
+                "X-Forwarded-For": "1.2.3.4",
+            },
+        )
+        assert resp.status_code == 302
+        # Should redirect to home app, not login or init
+        assert "/login" not in resp.headers["Location"]
+        assert "/init" not in resp.headers["Location"]
+
+    def test_basic_auth_wrong_password(self, configured_client):
+        """Basic Auth with wrong password → redirect to /login."""
+        creds = base64.b64encode(b":wrongpassword").decode()
+        resp = configured_client.get(
+            "/",
+            headers={
+                "Authorization": f"Basic {creds}",
+                "X-Forwarded-For": "1.2.3.4",
+            },
+        )
+        assert resp.status_code == 302
+        assert "/login" in resp.headers["Location"]
+
+    def test_basic_auth_no_session(self, configured_client):
+        """Basic Auth does not create a session — next request without header fails."""
+        creds = base64.b64encode(b":test123").decode()
+        # First request with Basic Auth succeeds
+        resp1 = configured_client.get(
+            "/",
+            headers={
+                "Authorization": f"Basic {creds}",
+                "X-Forwarded-For": "1.2.3.4",
+            },
+        )
+        assert "/login" not in resp1.headers["Location"]
+
+        # Second request without Basic Auth → should redirect to login
+        resp2 = configured_client.get("/", headers={"X-Forwarded-For": "1.2.3.4"})
+        assert resp2.status_code == 302
+        assert "/login" in resp2.headers["Location"]
+
+
+class TestPartialInit:
+    """Tests for partial init resumption."""
+
+    def test_partial_init_redirects_to_init(self, fresh_client, journal_copy):
+        """password_hash set but no setup.completed_at → redirect to /init."""
+        # Set password through the init flow
+        fresh_client.post(
+            "/init/password",
+            json={"password": "securepass123"},
+            content_type="application/json",
+        )
+        # Now password_hash exists but no setup.completed_at
+        resp = fresh_client.get("/", headers={"X-Forwarded-For": "1.2.3.4"})
+        assert resp.status_code == 302
+        assert "/init" in resp.headers["Location"]
+
+    def test_partial_init_renders_with_has_password(self, fresh_client, journal_copy):
+        """Partial init: init page renders with sections unlocked."""
+        fresh_client.post(
+            "/init/password",
+            json={"password": "securepass123"},
+            content_type="application/json",
+        )
+        resp = fresh_client.get("/init")
+        assert resp.status_code == 200
+        # The has_password template var triggers unlockSections()
+        assert b"unlockSections()" in resp.data
+
+
+class TestSetupMigration:
+    """Tests for the _migrate_setup_completed migration."""
+
+    def test_migration_writes_setup_and_trust(self, journal_copy):
+        """App startup with password_hash but no setup.completed_at writes both."""
+        config = _read_config(journal_copy)
+        config.pop("setup", None)
+        config["convey"].pop("trust_localhost", None)
+        (journal_copy / "config" / "journal.json").write_text(
+            json.dumps(config, indent=2)
+        )
+
+        # create_app triggers the migration
+        create_app(str(journal_copy))
+
+        config = _read_config(journal_copy)
+        assert "completed_at" in config.get("setup", {})
+        assert config["convey"].get("trust_localhost") is True
+
+    def test_migration_idempotent(self, journal_copy):
+        """Running migration twice is a no-op."""
+        config = _read_config(journal_copy)
+        config.pop("setup", None)
+        config["convey"].pop("trust_localhost", None)
+        (journal_copy / "config" / "journal.json").write_text(
+            json.dumps(config, indent=2)
+        )
+
+        # First run triggers migration
+        create_app(str(journal_copy))
+        config1 = _read_config(journal_copy)
+        ts1 = config1["setup"]["completed_at"]
+
+        # Second run should be a no-op
+        create_app(str(journal_copy))
+        config2 = _read_config(journal_copy)
+        assert config2["setup"]["completed_at"] == ts1
+        assert config2["convey"]["trust_localhost"] is True

tests/verify_api.py

···
 class _HttpClient:
     """Minimal requests-like object for endpoint fetching."""
 
-    def __init__(self, base_url: str) -> None:
+    def __init__(self, base_url: str, password: str | None = None) -> None:
         self.base_url = base_url.rstrip("/")
+        self._auth = ("", password) if password else None
 
     def get(self, path: str, query_string: dict[str, Any] | None = None):
         import requests
 
-        return requests.get(f"{self.base_url}{path}", params=query_string)
+        return requests.get(
+            f"{self.base_url}{path}", params=query_string, auth=self._auth
+        )
 
 
 def _resolve_journal_path() -> str:
···
         "--base-url",
         help="Use HTTP mode against this base URL instead of Flask test client",
     )
+    parser.add_argument(
+        "--password",
+        help="Password for Basic Auth in HTTP mode",
+    )
     return parser.parse_args(argv)
 
 
-def make_client(base_url: str | None) -> Any:
+def make_client(base_url: str | None, password: str | None = None) -> Any:
     if base_url:
-        return _HttpClient(base_url)
+        return _HttpClient(base_url, password=password)
     journal_path = _resolve_journal_path()
     app = create_app(journal_path)
     app.config["TESTING"] = True
···
 
 def main(argv: list[str] | None = None) -> int:
     args = parse_args(argv)
-    client = make_client(args.base_url)
+    client = make_client(args.base_url, password=args.password)
     journal_path = resolve_journal_for_mode(args.base_url)
 
     if args.command == "verify":