Add encrypted per-browser API-key persistence (Supabase + invisible cookie tag, fail-safe)

README.md

@@ -33,10 +33,14 @@ The app walks you through five steps in the left sidebar:
 
 - **Bring your own key.** Each visitor enters their own provider API key
   (OpenAI, Anthropic, Gemini, or Groq) on the Setup page.
-- **The key is never stored.** It is held only in your browser session's
-  memory — never written to a file, never put in the server environment, and
-  never shared with other visitors. It is discarded when you reload or close
-  the page, so you re-enter it next visit.
+- **Your key is stored encrypted, remembered on your device.** So you don't
+  re-enter it each visit, the key is saved **encrypted** (Fernet) using a
+  secret derived from a random, invisible per-browser tag. The storage backend
+  (Supabase) only ever holds ciphertext; the tag is never sent to it, so one
+  visitor's key can't be read with another's tag, and the key is never put in
+  the server environment. Use **Clear Credentials** to remove it. If key
+  storage isn't configured, the app falls back to session-only (re-enter each
+  visit).
 - **Your files are session-only.** Uploaded dossier files are processed in a
   temporary, per-session location and are not persisted on the server.
 - Only a small, relevance-filtered slice of your text is ever sent to the AI

app/main.py

@@ -16,7 +16,9 @@ from app.config import (
     APP_TITLE, APP_TAGLINE,
     get_settings, reload_settings,
     get_saved_dossier_path, save_dossier_path,
+    apply_session_overrides,
 )
+from app.services import browser_tag, key_store
 from app.services.api_gate import ApiGateError, run_capability_test
 from app.services.folder_validator import validate
 from app.services.dossier_reader import read_dossier
@@ -243,6 +245,36 @@ def _render_sidebar(show_debug: bool) -> None:
     api_usage_panel.render(key_suffix="sidebar")
 
 
+def _try_restore_saved_config() -> None:
+    """Load this browser's saved (encrypted) Setup config from Supabase.
+
+    Runs once per session. Only acts when key storage is configured and the
+    session has no API key yet. On success it applies the saved provider /
+    model / key / vision settings into the session so the rest of the app —
+    including smart-landing's API check — proceeds as if the user just set up.
+
+    Entirely fail-safe (see :mod:`app.services.key_store`): any failure leaves
+    the session untouched and the user simply lands on Setup as before.
+    """
+    ss = st.session_state
+    if ss.get("_restore_done"):
+        return
+    if not key_store.is_configured():
+        ss["_restore_done"] = True
+        return
+    if get_settings().has_api_key:
+        ss["_restore_done"] = True
+        return
+    tag = browser_tag.get_or_create_tag()
+    if not tag:
+        return  # tag not available yet; try again on the next render
+    stored = key_store.load_config(tag)
+    ss["_restore_done"] = True
+    if stored:
+        apply_session_overrides(stored)
+        ss["_config_restored"] = True
+
+
 def _try_smart_landing(settings) -> None:
     """On a fresh session, silently restore Setup + Dossier if already done.
 
@@ -349,6 +381,12 @@ def main() -> None:
     # Job Screenshot so they never have to re-enter their key or folder path.
     # We only do this once per session (guarded by the _smart_land_done flag),
     # and only when the session default "setup" is still the current step.
+    # Restore a previously saved (encrypted) config for this browser BEFORE
+    # smart-landing, so a returning visitor's key is in place and they get
+    # auto-advanced past Setup without re-entering anything.
+    _try_restore_saved_config()
+    settings = get_settings()
+
     if not st.session_state.get("_smart_land_done"):
         st.session_state["_smart_land_done"] = True
         _try_smart_landing(settings)

app/services/browser_tag.py

@@ -0,0 +1,82 @@
+"""Invisible per-browser identity — no login, nothing for the user to type.
+
+A returning visitor is recognised by a random **first-party cookie**:
+
+* It is READ synchronously from the page request via ``st.context.cookies`` —
+  reliable on every page load (unlike async localStorage components).
+* For a new browser it is MINTED and WRITTEN once via the same
+  ``window.parent`` bridge the theme already uses, so it survives reloads and
+  future visits.
+
+The minted value is also cached in ``st.session_state`` so the tag is stable
+within a session even before the cookie round-trips on the next reload.
+
+This tag is only an opaque identifier. The API key is encrypted *with* it (see
+:mod:`app.services.key_store`) and the tag itself is never sent to Supabase, so
+one browser's tag can't unlock another's stored key.
+
+Fully fail-safe: any problem (cookies disabled, API missing) returns ``None``
+and the app falls back to today's session-only behavior.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+import streamlit as st
+import streamlit.components.v1 as components
+
+_COOKIE = "ups_uid"
+_SESSION = "_browser_tag"
+_ONE_YEAR = 60 * 60 * 24 * 365
+
+
+def _read_cookie() -> str | None:
+    try:
+        value = st.context.cookies.get(_COOKIE)
+    except Exception:  # noqa: BLE001 - older/edge runtimes without cookie access
+        return None
+    return value or None
+
+
+def _write_cookie(value: str) -> None:
+    """Persist the tag as a first-party cookie on the app's document.
+
+    Sets it on ``window.parent.document`` (the real app page) from the 0-height
+    component iframe — the same parent bridge ``theme.apply_step_accent`` uses.
+    Takes effect on the next page load, which is exactly when we need to
+    recognise the returning visitor.
+    """
+    js = (
+        "<script>try{window.parent.document.cookie="
+        f"'{_COOKIE}={value}; path=/; max-age={_ONE_YEAR}; SameSite=Lax';"
+        "}catch(e){}</script>"
+    )
+    try:
+        components.html(js, height=0)
+    except Exception:  # noqa: BLE001 - fail-safe
+        pass
+
+
+def get_or_create_tag() -> str | None:
+    """Return this browser's stable tag, minting + persisting one if new.
+
+    Returns ``None`` only in the rare case neither a cookie nor minting is
+    possible; callers treat ``None`` as "no persistence this run".
+    """
+    ss = st.session_state
+    cached = ss.get(_SESSION)
+    if cached:
+        return cached
+
+    existing = _read_cookie()
+    if existing:
+        ss[_SESSION] = existing
+        return existing
+
+    # New browser: mint now (usable immediately this session) and persist a
+    # cookie so the next visit is recognised.
+    tag = secrets.token_urlsafe(32)
+    ss[_SESSION] = tag
+    _write_cookie(tag)
+    return tag

app/services/key_store.py

@@ -0,0 +1,185 @@
+"""Encrypted, per-browser persistence of the Setup config (incl. API key).
+
+Goal: a visitor enters their API key once and, on the same browser, never has
+to re-enter it — without any login or any code they must remember. A random,
+invisible per-browser *tag* identifies the returning visitor (see
+:mod:`app.services.browser_tag`); this module stores their config in Supabase,
+encrypted so that:
+
+* Supabase only ever holds **ciphertext** — a DB/storage leak reveals nothing.
+* The encryption secret is derived from the browser tag, which is **never sent
+  to Supabase**, so one visitor's stored blob can't be read with another's tag.
+* The storage object id is derived from the tag with a *different* salt than the
+  encryption key, so even the id can't be turned back into the decryption key.
+
+Everything here is **fail-safe**: if Supabase isn't configured, or any network
+call fails, every function quietly degrades to a no-op / ``None`` and the app
+falls back to today's session-only behavior. It must never raise into the UI.
+
+Storage backend: a private Supabase Storage bucket (auto-created on first use),
+one small object per browser tag. Using Storage means no database schema / SQL
+setup is required — the bucket is created via the service key at runtime.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from typing import Optional
+
+# Bucket that holds the encrypted per-tag config blobs.
+_BUCKET = "apikeys"
+_TIMEOUT = 8.0
+# Salts keep the storage-object id and the encryption key independent, so
+# knowing the id (which Supabase stores) never yields the decryption key.
+_ID_SALT = b"upwork-strategist::object-id::v1"
+_KEY_SALT = b"upwork-strategist::enc-key::v1"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+def is_configured() -> bool:
+    """True only when the Supabase service credentials are present."""
+    return bool(_base_url() and _service_key())
+
+
+def _base_url() -> str:
+    return (os.getenv("SUPABASE_URL") or "").rstrip("/")
+
+
+def _service_key() -> str:
+    return os.getenv("SUPABASE_SERVICE_KEY") or ""
+
+
+# ---------------------------------------------------------------------------
+# Crypto / id derivation (pure, unit-testable)
+# ---------------------------------------------------------------------------
+def _object_path(tag: str) -> str:
+    digest = hashlib.sha256(_ID_SALT + tag.encode("utf-8")).hexdigest()
+    return f"{digest}.bin"
+
+
+def _fernet(tag: str):
+    from cryptography.fernet import Fernet
+
+    raw = hashlib.sha256(_KEY_SALT + tag.encode("utf-8")).digest()
+    return Fernet(base64.urlsafe_b64encode(raw))
+
+
+def encrypt_payload(tag: str, payload: dict) -> bytes:
+    """Encrypt a config dict for ``tag`` -> ciphertext bytes (pure)."""
+    data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    return _fernet(tag).encrypt(data)
+
+
+def decrypt_payload(tag: str, token: bytes) -> Optional[dict]:
+    """Decrypt ciphertext for ``tag`` -> config dict, or ``None`` if it can't
+    be decrypted with this tag (wrong tag / corrupt / tampered)."""
+    from cryptography.fernet import InvalidToken
+
+    try:
+        plain = _fernet(tag).decrypt(token)
+        obj = json.loads(plain)
+        return obj if isinstance(obj, dict) else None
+    except (InvalidToken, ValueError, TypeError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# HTTP transport (single seam — monkeypatched in tests)
+# ---------------------------------------------------------------------------
+def _http(method: str, url: str, headers: dict, content: Optional[bytes] = None):
+    """Perform one HTTP request. Returns ``(status_code, body_bytes)``.
+
+    Isolated so tests can replace it with an in-memory fake. Uses ``httpx``,
+    which is already installed (httpx is an OpenAI SDK dependency).
+    """
+    import httpx
+
+    with httpx.Client(timeout=_TIMEOUT) as client:
+        resp = client.request(method, url, headers=headers, content=content)
+        return resp.status_code, resp.content
+
+
+def _auth_headers(extra: Optional[dict] = None) -> dict:
+    key = _service_key()
+    headers = {"Authorization": f"Bearer {key}", "apikey": key}
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def _ensure_bucket() -> None:
+    """Create the private bucket if missing. Idempotent; errors are ignored
+    (a 'already exists' response is the normal case after the first run)."""
+    url = f"{_base_url()}/storage/v1/bucket"
+    body = json.dumps({"id": _BUCKET, "name": _BUCKET, "public": False}).encode()
+    try:
+        _http("POST", url, _auth_headers({"Content-Type": "application/json"}), body)
+    except Exception:  # noqa: BLE001 - best-effort; save() will surface real failure
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Public API (fail-safe)
+# ---------------------------------------------------------------------------
+def save_config(tag: str, payload: dict) -> bool:
+    """Encrypt ``payload`` under ``tag`` and upsert it to Supabase.
+
+    Returns True on success, False on any failure or when not configured.
+    Never raises.
+    """
+    if not (is_configured() and tag and payload):
+        return False
+    try:
+        _ensure_bucket()
+        token = encrypt_payload(tag, payload)
+        url = f"{_base_url()}/storage/v1/object/{_BUCKET}/{_object_path(tag)}"
+        # x-upsert overwrites an existing object for this tag.
+        status, _ = _http(
+            "POST",
+            url,
+            _auth_headers(
+                {"Content-Type": "application/octet-stream", "x-upsert": "true"}
+            ),
+            token,
+        )
+        return 200 <= status < 300
+    except Exception:  # noqa: BLE001 - fail-safe: never break the UI
+        return False
+
+
+def load_config(tag: str) -> Optional[dict]:
+    """Fetch and decrypt the stored config for ``tag``.
+
+    Returns the config dict, or ``None`` if absent / not configured / any
+    failure. Never raises.
+    """
+    if not (is_configured() and tag):
+        return None
+    try:
+        url = f"{_base_url()}/storage/v1/object/{_BUCKET}/{_object_path(tag)}"
+        status, body = _http("GET", url, _auth_headers())
+        if not (200 <= status < 300) or not body:
+            return None
+        return decrypt_payload(tag, body)
+    except Exception:  # noqa: BLE001 - fail-safe
+        return None
+
+
+def delete_config(tag: str) -> bool:
+    """Remove the stored config for ``tag`` (used by Clear Credentials).
+
+    Returns True on success, False otherwise. Never raises.
+    """
+    if not (is_configured() and tag):
+        return False
+    try:
+        url = f"{_base_url()}/storage/v1/object/{_BUCKET}/{_object_path(tag)}"
+        status, _ = _http("DELETE", url, _auth_headers())
+        return 200 <= status < 300
+    except Exception:  # noqa: BLE001 - fail-safe
+        return False

app/ui/setup_screen.py

@@ -2,11 +2,14 @@
 
 This is the only onboarding step a user needs. They pick a provider, model,
 and (vision) model and paste their API key directly into the **Configure AI
-Service** form; clicking *Save Configuration* keeps those values in this
-browser session's memory only — the API key is never written to disk or to
-``os.environ`` (so it can't persist or leak to another visitor on a shared
-deployment) and is discarded on page reload. They then click *Run API Check*
-to confirm the service is reachable, which unlocks the rest of the flow.
+Service** form; clicking *Save Configuration* applies those values to the
+session and, when key storage is configured, also remembers them across visits
+by saving them to Supabase **encrypted with this browser's invisible tag**
+(Supabase only ever holds ciphertext; the key is never written to ``os.environ``
+and never readable by another visitor). They then click *Run API Check* to
+confirm the service is reachable, which unlocks the rest of the flow. On a
+return visit the saved config is decrypted and restored automatically, so they
+skip Setup entirely. See :mod:`app.services.key_store` / `browser_tag`.
 
 Internal data-handling rules (kept in code/README, not surfaced as a
 required UI step):
@@ -41,6 +44,7 @@ from app.config import (
     reload_settings,
 )
 from app.models.provider_models import get_text_models, get_vision_models
+from app.services import browser_tag, key_store
 from app.services.api_gate import ApiGateError, run_capability_test
 from app.ui import theme
 
@@ -216,11 +220,16 @@ def _handle_config_save(
         proposal_max_output_tokens=proposal_max_output_tokens,
         log_retention_days=log_retention_days,
     )
-    # ``updates`` holds the raw key — stored in this browser session's memory
-    # only (never on disk or in os.environ), so it is gone on page reload and
-    # never leaks to another visitor on a shared deployment. Never logged.
+    # ``updates`` holds the raw key — applied to this browser session's memory
+    # (never on disk or in os.environ). Never logged.
     apply_session_overrides(updates)
 
+    # Remember it for next time: persist the config to Supabase, ENCRYPTED with
+    # this browser's invisible tag (Supabase only ever holds ciphertext). Fully
+    # fail-safe — if storage isn't configured or the call fails, nothing happens
+    # and the app simply behaves session-only.
+    _persist_config_to_store()
+
     # Clear stale gate state so the next step re-locks until the new config
     # passes the API check.
     for key in _API_STATE_KEYS:
@@ -231,10 +240,38 @@ def _handle_config_save(
     st.rerun()
 
 
+def _persist_config_to_store() -> None:
+    """Save the current session config to Supabase, encrypted per-browser.
+
+    No-op unless key storage is configured AND there is an API key to remember.
+    Never raises (see :mod:`app.services.key_store`).
+    """
+    if not key_store.is_configured():
+        return
+    overrides = config.export_session_overrides()
+    payload = {
+        k: v
+        for k, v in overrides.items()
+        if isinstance(v, str) and k.isupper() and k != "DOSSIER_FOLDER_PATH"
+    }
+    if not any(payload.get(name) for name in config._PROVIDER_API_KEY_ENV):
+        return  # nothing worth remembering yet
+    tag = browser_tag.get_or_create_tag()
+    if tag:
+        key_store.save_config(tag, payload)
+
+
 def _handle_clear_credentials() -> None:
     """Wipe every API key from this session's memory and re-lock the API gate."""
     config.clear_session_api_keys()
 
+    # Also forget the encrypted copy stored for this browser, so "Clear
+    # Credentials" truly removes it everywhere.
+    if key_store.is_configured():
+        tag = browser_tag.get_or_create_tag()
+        if tag:
+            key_store.delete_config(tag)
+
     # Drop any typed key from widget state so nothing is re-rendered, then
     # re-lock the gate: with no key saved, the rest of the flow must stay
     # locked until a new key is saved and the check passes again.
@@ -332,9 +369,10 @@ def _render_config_form(settings) -> None:
         theme.section_label("Configure AI Service")
         st.write(
             "Enter your AI service details and click Save Configuration. "
-            "Your API key is kept in this browser session's memory only — it "
-            "is never written to a file and is discarded when you reload or "
-            "close the page. You'll re-enter it next time you open the app."
+            "Your API key is **encrypted and remembered on this device**, so "
+            "you won't need to re-enter it next time. It is stored encrypted "
+            "(never in plain text), never shared with other visitors, and you "
+            "can remove it any time with Clear Credentials."
         )
         if just_saved:
             st.success("Configuration saved. Run API Check to continue.")
@@ -342,7 +380,7 @@ def _render_config_form(settings) -> None:
             st.success("Saved credentials cleared. Enter a new API key to continue.")
         masked = _saved_key_status(settings)
         if masked:
-            st.caption(f"Key entered this session for the current provider: {masked}")
+            st.caption(f"Key remembered on this device for the current provider: {masked}")
 
         # --- Text / LLM settings ---------------------------------------
         provider = st.selectbox(
@@ -366,8 +404,8 @@ def _render_config_form(settings) -> None:
             key=_FORM_API_KEY,
             type="password",
             help=(
-                "Held in this session's memory only, never saved to disk. "
-                "Leave blank to keep the key already entered this session."
+                "Stored encrypted and remembered on this device. "
+                "Leave blank to keep the key you already saved."
             ),
         )
 

requirements.txt

@@ -12,6 +12,13 @@ streamlit==1.55.0
 pydantic==2.12.5
 python-dotenv==1.2.2
 
+# --- Encrypted per-browser key storage (Supabase-backed) ---
+# `cryptography` encrypts the saved Setup config (Fernet); `httpx` (already a
+# dependency of the OpenAI SDK) makes the Supabase Storage REST calls. Both are
+# imported directly by app/services/key_store.py, so they are pinned here.
+cryptography==46.0.6
+httpx==0.28.1
+
 # --- Optional UI: clipboard paste on the Job Screenshot screen ---
 # Lets a user paste a copied screenshot directly into the app. The screen
 # degrades gracefully to drag-drop/browse if this is absent (the import is