From 6f658495e81d763955c7ab16a606b32994446605 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:10:33 -0700
Subject: [PATCH 01/14] fix(auth): keep the auth cache out of the invocation
directory
Refs #620
---
AGENTS.md | 2 +-
selftests/test_auth_cache.py | 115 ++++++++++++++++++++++++++++++++++-
src/vip/auth/cache.py | 44 +++++++++++---
3 files changed, 150 insertions(+), 11 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 9ef34d3ae..9656adbc9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -180,7 +180,7 @@ Key principles:
| `src/vip/cli/` | CLI entry point, one module per command: `version.py`, `verify.py` (including `--basic` to skip `@slow`-tagged scenarios), `cleanup.py` (Connect content + orphaned Workbench sessions via `--workbench-url`), `install.py` (install, uninstall), `auth.py`, `report.py`, `status.py`, `scaffold.py`; `app.py` builds the parser and holds `main()` and the `--version` flag; `_common.py` holds helpers shared by several commands; `__init__.py` re-exports the names callers import from `vip.cli`, but a selftest must patch a helper on the submodule that calls it |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location (both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 26b621cd9..b7287c592 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import os
import sys
from typing import ClassVar
@@ -30,6 +31,42 @@ def _make_session(self, tmp_path, *, connect_url: str, api_key: str | None):
_connect_url=connect_url,
)
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permission bits")
+ def test_creates_the_cache_directory_owner_only(self, tmp_path):
+ from vip.auth import _save_auth_cache
+
+ session = self._make_session(tmp_path, connect_url="", api_key=None)
+ cache = tmp_path / "a" / "b" / ".vip-auth-cache.json"
+
+ _save_auth_cache(session, cache)
+
+ assert cache.exists()
+ assert cache.parent.stat().st_mode & 0o777 == 0o700
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permission bits")
+ @pytest.mark.skipif(
+ hasattr(os, "geteuid") and os.geteuid() == 0, reason="root ignores directory permissions"
+ )
+ def test_unwritable_cache_root_skips_caching_without_raising(
+ self, tmp_path, monkeypatch, capsys
+ ):
+ from vip.auth import _save_auth_cache
+
+ session = self._make_session(tmp_path, connect_url="", api_key=None)
+ locked = tmp_path / "locked"
+ locked.mkdir()
+ locked.chmod(0o500)
+ work = tmp_path / "work"
+ work.mkdir()
+ monkeypatch.chdir(work)
+ try:
+ _save_auth_cache(session, locked / "vip" / ".vip-auth-cache.json")
+ finally:
+ locked.chmod(0o700)
+
+ assert "Skipping auth cache" in capsys.readouterr().out
+ assert not list(work.glob(".vip-auth-cache*"))
+
def test_skips_cache_when_connect_configured_but_mint_failed(self, tmp_path):
from vip.auth import _save_auth_cache
@@ -561,11 +598,85 @@ class TestAuthCachePath:
silently disagreed and ``vip cleanup`` looked in the wrong place.
"""
- def test_resolves_relative_to_the_invocation_directory(self, tmp_path, monkeypatch):
+ def test_lives_under_the_user_cache_root_not_cwd(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ work, cache_home = tmp_path / "work", tmp_path / "xdg"
+ work.mkdir()
+ monkeypatch.chdir(work)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(cache_home))
+
+ p = auth_cache_path()
+
+ assert p.name == ".vip-auth-cache.json"
+ assert p.parent.parent == cache_home / "vip" / "auth"
+ assert len(p.parent.name) == 16
+ assert work.resolve() not in p.parents
+
+ def test_is_keyed_on_the_invocation_directory(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
+ (tmp_path / "a").mkdir()
+ (tmp_path / "b").mkdir()
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+
+ monkeypatch.chdir(tmp_path / "a")
+ first = auth_cache_path()
+ monkeypatch.chdir(tmp_path / "b")
+ second = auth_cache_path()
+
+ assert first.parent != second.parent
+ assert first.parent.parent == second.parent.parent
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="symlinks need privileges on Windows")
+ def test_symlinked_cwd_resolves_to_the_same_cache(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ real = tmp_path / "real"
+ real.mkdir()
+ link = tmp_path / "link"
+ link.symlink_to(real, target_is_directory=True)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+
+ monkeypatch.chdir(real)
+ via_real = auth_cache_path()
+ monkeypatch.chdir(link)
+ via_link = auth_cache_path()
+
+ assert via_real == via_link
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="Windows ignores HOME and XDG_CACHE_HOME")
+ def test_relative_xdg_cache_home_is_ignored(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ home = tmp_path / "home"
+ home.mkdir()
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("XDG_CACHE_HOME", "rel")
+ monkeypatch.setenv("HOME", str(home))
+
+ assert auth_cache_path().parent.parent == home / ".cache" / "vip" / "auth"
+
+ def test_windows_uses_localappdata(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setattr(sys, "platform", "win32")
+ monkeypatch.delenv("XDG_CACHE_HOME", raising=False)
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "lad"))
+
+ assert auth_cache_path().parent.parent == tmp_path / "lad" / "vip" / "auth"
+
+ def test_resolving_the_path_creates_nothing(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ cache_home = tmp_path / "xdg"
monkeypatch.chdir(tmp_path)
- assert auth_cache_path() == tmp_path / ".vip-auth-cache.json"
+ monkeypatch.setenv("XDG_CACHE_HOME", str(cache_home))
+
+ auth_cache_path()
+
+ assert not cache_home.exists()
def test_call_sites_do_not_build_the_path_inline(self):
"""Invariant: the filename literal lives in one place. A second inline
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 05dfc008e..84a845918 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -3,9 +3,11 @@
from __future__ import annotations
import contextlib
+import hashlib
import json
import logging
import os
+import sys
import tempfile
import time
from pathlib import Path
@@ -35,6 +37,21 @@
_CACHE_DROPPED_COOKIES = frozenset({"ESTSAUTHPERSISTENT"})
+def _user_cache_root() -> Path:
+ """Per-user cache root: ``$XDG_CACHE_HOME``, ``%LOCALAPPDATA%`` on Windows, else ``~/.cache``.
+
+ A relative ``XDG_CACHE_HOME`` is ignored, as the XDG spec requires. Creates nothing.
+ """
+ xdg = os.environ.get("XDG_CACHE_HOME")
+ if xdg and Path(xdg).is_absolute():
+ return Path(xdg)
+ if sys.platform == "win32":
+ local_app_data = os.environ.get("LOCALAPPDATA")
+ if local_app_data:
+ return Path(local_app_data)
+ return Path.home() / ".cache"
+
+
def auth_cache_path() -> Path:
"""Path to the auth-session cache for the current invocation directory.
@@ -48,8 +65,13 @@ def auth_cache_path() -> Path:
invocation directory and the ``site-packages`` test paths — which lands in
``$HOME``. That put the cache nowhere near the user's ``vip.toml`` and made
the two call sites read different files.
+
+ The cache lives under the user cache directory, not in the invocation directory:
+ cwd is what users zip and share, and the cache holds a live session and API key
+ (#620). The directory is not created here; :func:`_save_auth_cache` does that.
"""
- return Path.cwd() / AUTH_CACHE_FILENAME
+ key = hashlib.sha256(str(Path.cwd().resolve()).encode("utf-8")).hexdigest()[:16]
+ return _user_cache_root() / "vip" / "auth" / key / AUTH_CACHE_FILENAME
def _cookies_from_storage_state(storage_state_path: Path) -> httpx.Cookies:
@@ -392,11 +414,6 @@ def _save_auth_cache(session: InteractiveAuthSession, cache_path: Path) -> None:
# Write the storage state to the cache location, minus long-lived IdP cookies.
state = json.loads(session.storage_state_path.read_text(encoding="utf-8"))
- fd = os.open(cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
- with os.fdopen(fd, "w", encoding="utf-8") as handle:
- json.dump(_cacheable_storage_state(state), handle)
- cache_path.chmod(0o600)
-
# Write companion metadata. ``connect_url`` keeps the resolved
# form (used for API key cleanup); ``requested_connect_url`` keeps
# the pre-resolve form for cache-key matching. Older releases only
@@ -411,5 +428,16 @@ def _save_auth_cache(session: InteractiveAuthSession, cache_path: Path) -> None:
"requested_connect_url": session._requested_connect_url or session._connect_url,
"workbench_url": session._workbench_url,
}
- meta_path.write_text(json.dumps(meta), encoding="utf-8")
- meta_path.chmod(0o600)
+ try:
+ cache_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ fd = os.open(cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ json.dump(_cacheable_storage_state(state), handle)
+ cache_path.chmod(0o600)
+ meta_path.write_text(json.dumps(meta), encoding="utf-8")
+ meta_path.chmod(0o600)
+ except OSError as exc:
+ print(
+ f">>> Skipping auth cache: cannot write {cache_path.parent} ({exc}); "
+ "next run will re-authenticate."
+ )
From f9e1d13ed4326c86b6c0be4958793eb45135d4de Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:14:15 -0700
Subject: [PATCH 02/14] fix(auth): move existing auth caches out of the
invocation directory
Refs #620
---
selftests/test_auth_cache.py | 113 ++++++++++++++++++++++++++++++++++-
src/vip/auth/cache.py | 33 +++++++++-
2 files changed, 143 insertions(+), 3 deletions(-)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index b7287c592..157ab2b98 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -2,8 +2,10 @@
from __future__ import annotations
+import errno
import os
import sys
+import time
from typing import ClassVar
import pytest
@@ -667,7 +669,7 @@ def test_windows_uses_localappdata(self, tmp_path, monkeypatch):
assert auth_cache_path().parent.parent == tmp_path / "lad" / "vip" / "auth"
- def test_resolving_the_path_creates_nothing(self, tmp_path, monkeypatch):
+ def test_resolving_creates_nothing_without_a_legacy_cache(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
cache_home = tmp_path / "xdg"
@@ -698,6 +700,115 @@ def test_call_sites_do_not_build_the_path_inline(self):
assert ".vip-auth-cache.json" in _Path(vip.auth.cache.__file__).read_text(encoding="utf-8")
+class TestLegacyAuthCacheMigration:
+ """Caches an older VIP wrote into the invocation directory move to the user
+ cache dir exactly once, so a live session and API key stop sitting in cwd (#620).
+ """
+
+ @staticmethod
+ def _legacy(work, state="STATE", meta="META"):
+ work.mkdir(exist_ok=True)
+ (work / ".vip-auth-cache.json").write_text(state, encoding="utf-8")
+ (work / ".vip-auth-cache.meta.json").write_text(meta, encoding="utf-8")
+
+ @staticmethod
+ def _dest(tmp_path):
+ return tmp_path / "xdg" / "vip" / "auth" / "abc" / ".vip-auth-cache.json"
+
+ def test_moves_both_legacy_files_out_of_cwd(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert dest.read_text(encoding="utf-8") == "STATE"
+ assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "META"
+
+ def test_keeps_mtime_so_the_ttl_still_applies(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ old = time.time() - 5 * 3600
+ os.utime(work / ".vip-auth-cache.json", (old, old))
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert abs(dest.stat().st_mtime - old) < 1
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX file modes do not apply on Windows")
+ def test_moved_files_are_owner_only(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ (work / ".vip-auth-cache.json").chmod(0o644)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert dest.stat().st_mode & 0o777 == 0o600
+ assert dest.with_suffix(".meta.json").stat().st_mode & 0o777 == 0o600
+ assert dest.parent.stat().st_mode & 0o777 == 0o700
+
+ def test_cross_device_move_still_lands(self, tmp_path, monkeypatch):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ def fail(*args, **kwargs):
+ raise OSError(errno.EXDEV, "x")
+
+ monkeypatch.setattr(os, "rename", fail)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert dest.read_text(encoding="utf-8") == "STATE"
+ assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "META"
+
+ def test_existing_dest_wins_and_legacy_is_deleted(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ dest.parent.mkdir(parents=True)
+ dest.write_text("NEW", encoding="utf-8")
+ dest.with_suffix(".meta.json").write_text("NEWMETA", encoding="utf-8")
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert dest.read_text(encoding="utf-8") == "NEW"
+ assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "NEWMETA"
+ assert list(work.glob(".vip-auth-cache*")) == []
+
+ def test_is_a_no_op_when_there_is_nothing_to_move(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ work.mkdir()
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert not dest.parent.exists()
+
+ def test_auth_cache_path_migrates_on_resolve(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ work = tmp_path / "work"
+ self._legacy(work)
+ monkeypatch.chdir(work)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+
+ path = auth_cache_path()
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert path.read_text(encoding="utf-8") == "STATE"
+
+
class TestStaleCacheTriggersReauth:
"""End-to-end wiring: a dead cached session must fall through to the real
auth flow, not be handed to the tests. The helper-level tests above prove
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 84a845918..7c4e9fa7d 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -7,6 +7,7 @@
import json
import logging
import os
+import shutil
import sys
import tempfile
import time
@@ -68,10 +69,38 @@ def auth_cache_path() -> Path:
The cache lives under the user cache directory, not in the invocation directory:
cwd is what users zip and share, and the cache holds a live session and API key
- (#620). The directory is not created here; :func:`_save_auth_cache` does that.
+ (#620). The directory is not created here; :func:`_save_auth_cache` does that, except
+ when :func:`_migrate_legacy_auth_cache` finds an old cache in cwd to move.
"""
key = hashlib.sha256(str(Path.cwd().resolve()).encode("utf-8")).hexdigest()[:16]
- return _user_cache_root() / "vip" / "auth" / key / AUTH_CACHE_FILENAME
+ path = _user_cache_root() / "vip" / "auth" / key / AUTH_CACHE_FILENAME
+ _migrate_legacy_auth_cache(Path.cwd(), path)
+ return path
+
+
+def _migrate_legacy_auth_cache(legacy_dir: Path, dest: Path) -> None:
+ """Move caches an older VIP wrote into ``legacy_dir`` to ``dest``, never raising.
+
+ A live session and API key must not stay in a directory users zip and share (#620),
+ so a file that cannot be moved is deleted. Idempotent: with nothing in ``legacy_dir``
+ it does nothing.
+ """
+ for target in (dest, dest.with_suffix(".meta.json")):
+ legacy = legacy_dir / target.name
+ if legacy == target or not legacy.is_file():
+ continue
+ try:
+ if not target.exists():
+ target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ shutil.move(str(legacy), str(target))
+ target.chmod(0o600)
+ else:
+ legacy.unlink()
+ except OSError:
+ try:
+ legacy.unlink()
+ except OSError:
+ logger.warning("Could not remove legacy auth cache %s; delete it by hand.", legacy)
def _cookies_from_storage_state(storage_state_path: Path) -> httpx.Cookies:
From 4c2182fb71bfea949efed484f2f06650cf45745e Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:16:05 -0700
Subject: [PATCH 03/14] fix(auth): tolerate concurrent auth cache migration
Refs #620
---
selftests/test_auth_cache.py | 84 ++++++++++++++++++++++++++++++++++++
src/vip/auth/cache.py | 4 +-
2 files changed, 86 insertions(+), 2 deletions(-)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 157ab2b98..2de9fe304 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -4,6 +4,7 @@
import errno
import os
+import pathlib
import sys
import time
from typing import ClassVar
@@ -763,9 +764,13 @@ def fail(*args, **kwargs):
raise OSError(errno.EXDEV, "x")
monkeypatch.setattr(os, "rename", fail)
+ old = time.time() - 5 * 3600
+ os.utime(work / ".vip-auth-cache.json", (old, old))
_migrate_legacy_auth_cache(work, dest)
+ assert abs(dest.stat().st_mtime - old) < 1
+
assert list(work.glob(".vip-auth-cache*")) == []
assert dest.read_text(encoding="utf-8") == "STATE"
assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "META"
@@ -785,6 +790,85 @@ def test_existing_dest_wins_and_legacy_is_deleted(self, tmp_path):
assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "NEWMETA"
assert list(work.glob(".vip-auth-cache*")) == []
+ def test_failed_move_deletes_the_legacy_file_quietly(self, tmp_path, monkeypatch, caplog):
+ import shutil
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ def fail(*args, **kwargs):
+ raise OSError(errno.EACCES, "denied")
+
+ monkeypatch.setattr(shutil, "move", fail)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert caplog.records == []
+
+ def test_failed_move_and_failed_delete_warns_with_the_path(self, tmp_path, monkeypatch, caplog):
+ import shutil
+ from pathlib import Path
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ def fail(*args, **kwargs):
+ raise OSError(errno.EACCES, "denied")
+
+ monkeypatch.setattr(shutil, "move", fail)
+ monkeypatch.setattr(Path, "unlink", fail)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ warned = [r.getMessage() for r in caplog.records if r.levelname == "WARNING"]
+ assert any(str(work / ".vip-auth-cache.json") in m for m in warned)
+ assert any(str(work / ".vip-auth-cache.meta.json") in m for m in warned)
+
+ def test_legacy_file_vanishing_mid_migration_is_not_an_error(
+ self, tmp_path, monkeypatch, caplog
+ ):
+ import shutil
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ def lose_race(src, dst):
+ pathlib.Path(src).unlink()
+ raise FileNotFoundError(errno.ENOENT, "gone")
+
+ monkeypatch.setattr(shutil, "move", lose_race)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert caplog.records == []
+
+ def test_legacy_vanishing_before_delete_when_dest_wins_is_not_an_error(
+ self, tmp_path, monkeypatch, caplog
+ ):
+ from pathlib import Path
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ work.mkdir()
+ dest.parent.mkdir(parents=True)
+ dest.write_text("NEW", encoding="utf-8")
+ dest.with_suffix(".meta.json").write_text("NEWMETA", encoding="utf-8")
+ monkeypatch.setattr(Path, "is_file", lambda self: True)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert dest.read_text(encoding="utf-8") == "NEW"
+ assert caplog.records == []
+
def test_is_a_no_op_when_there_is_nothing_to_move(self, tmp_path):
from vip.auth.cache import _migrate_legacy_auth_cache
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 7c4e9fa7d..80dfd3be1 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -95,10 +95,10 @@ def _migrate_legacy_auth_cache(legacy_dir: Path, dest: Path) -> None:
shutil.move(str(legacy), str(target))
target.chmod(0o600)
else:
- legacy.unlink()
+ legacy.unlink(missing_ok=True)
except OSError:
try:
- legacy.unlink()
+ legacy.unlink(missing_ok=True)
except OSError:
logger.warning("Could not remove legacy auth cache %s; delete it by hand.", legacy)
From 62a982640ed7c24ba476836b308861b89d5beccc Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:17:43 -0700
Subject: [PATCH 04/14] docs: say where VIP keeps credentials on disk
Refs #620
---
AGENTS.md | 2 +-
README.md | 16 ++++++++++++++++
vip.toml.example | 1 +
3 files changed, 18 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
index 9656adbc9..b5a87447d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -180,7 +180,7 @@ Key principles:
| `src/vip/cli/` | CLI entry point, one module per command: `version.py`, `verify.py` (including `--basic` to skip `@slow`-tagged scenarios), `cleanup.py` (Connect content + orphaned Workbench sessions via `--workbench-url`), `install.py` (install, uninstall), `auth.py`, `report.py`, `status.py`, `scaffold.py`; `app.py` builds the parser and holds `main()` and the `--version` flag; `_common.py` holds helpers shared by several commands; `__init__.py` re-exports the names callers import from `vip.cli`, but a selftest must patch a helper on the submodule that calls it |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (the first resolve moves a legacy cwd cache there; both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/README.md b/README.md
index 282aad5c3..2fcc5eb9d 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,22 @@ Fast confidence check — skip the detailed/long-running checks:
vip verify --config vip.toml --basic
```
+### Credentials on disk
+
+`--interactive-auth` and `--headless-auth` cache a live session for 4 hours:
+the identity provider (IdP), Connect, and Workbench cookies, plus a Connect
+API key that VIP creates. The cache lives in `~/.cache/vip/auth/` (`$XDG_CACHE_HOME/vip/auth/` if set, or
+`%LOCALAPPDATA%\vip\auth\` on Windows). Delete that directory to drop it.
+
+Earlier releases wrote `.vip-auth-cache.json` and `.vip-auth-cache.meta.json`
+into the working directory. The first run of this release moves them. Never
+share those files.
+
+`vip.toml` can hold `api_key` and `password` values. Remove or redact them
+before you share a VIP directory. Prefer the `VIP_CONNECT_API_KEY`,
+`VIP_WORKBENCH_API_KEY`, and `VIP_TEST_PASSWORD` environment variables over
+inline secrets.
+
## Uninstalling
To reverse what `vip install` (or `just setup`) did:
diff --git a/vip.toml.example b/vip.toml.example
index 07df4e454..9789c6209 100644
--- a/vip.toml.example
+++ b/vip.toml.example
@@ -30,6 +30,7 @@ url = "https://connect.example.com"
# API key for a Connect admin user.
# Prefer setting the VIP_CONNECT_API_KEY environment variable.
+# Never share this file with a real key in it.
# api_key = "..."
# Timeout in seconds for content deployments (default: 1200)
From 519c89755510ebf2e1042c386dd0519e18b9a760 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 10:35:11 -0700
Subject: [PATCH 05/14] fix(auth): skip the auth cache when no home directory
exists
Refs #620
---
AGENTS.md | 2 +-
README.md | 3 ++-
selftests/test_auth_cache.py | 32 ++++++++++++++++++++++++++++++++
selftests/test_cli_cleanup.py | 22 ++++++++++++++++++++++
src/vip/auth/cache.py | 17 ++++++++++++++---
5 files changed, 71 insertions(+), 5 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index b5a87447d..39a8e31ef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -180,7 +180,7 @@ Key principles:
| `src/vip/cli/` | CLI entry point, one module per command: `version.py`, `verify.py` (including `--basic` to skip `@slow`-tagged scenarios), `cleanup.py` (Connect content + orphaned Workbench sessions via `--workbench-url`), `install.py` (install, uninstall), `auth.py`, `report.py`, `status.py`, `scaffold.py`; `app.py` builds the parser and holds `main()` and the `--version` flag; `_common.py` holds helpers shared by several commands; `__init__.py` re-exports the names callers import from `vip.cli`, but a selftest must patch a helper on the submodule that calls it |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (the first resolve moves a legacy cwd cache there; both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (returns `None` and skips caching when no home directory exists; the first resolve moves a legacy cwd cache there; both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/README.md b/README.md
index 2fcc5eb9d..5849dcbec 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,8 @@ vip verify --config vip.toml --basic
`--interactive-auth` and `--headless-auth` cache a live session for 4 hours:
the identity provider (IdP), Connect, and Workbench cookies, plus a Connect
API key that VIP creates. The cache lives in `~/.cache/vip/auth/` (`$XDG_CACHE_HOME/vip/auth/` if set, or
-`%LOCALAPPDATA%\vip\auth\` on Windows). Delete that directory to drop it.
+`%LOCALAPPDATA%\vip\auth\` on Windows). Delete that directory to drop it. With no home
+directory and no `XDG_CACHE_HOME`, VIP skips the cache.
Earlier releases wrote `.vip-auth-cache.json` and `.vip-auth-cache.meta.json`
into the working directory. The first run of this release moves them. Never
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 2de9fe304..551e20c92 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -681,6 +681,38 @@ def test_resolving_creates_nothing_without_a_legacy_cache(self, tmp_path, monkey
assert not cache_home.exists()
+ def _no_home(self, tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("XDG_CACHE_HOME", raising=False)
+ monkeypatch.setattr(sys, "platform", "linux")
+
+ def _raise():
+ raise RuntimeError("Could not determine home directory.")
+
+ monkeypatch.setattr(pathlib.Path, "home", _raise)
+
+ def test_no_home_directory_skips_the_cache(self, tmp_path, monkeypatch, capsys):
+ from vip.auth import auth_cache_path
+
+ self._no_home(tmp_path, monkeypatch)
+ before = set(tmp_path.iterdir())
+
+ assert auth_cache_path() is None
+
+ assert "Skipping auth cache" in capsys.readouterr().out
+ assert set(tmp_path.iterdir()) == before
+
+ def test_no_home_directory_leaves_legacy_cache_alone(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ self._no_home(tmp_path, monkeypatch)
+ legacy = tmp_path / ".vip-auth-cache.json"
+ legacy.write_text('{"cookies": []}', encoding="utf-8")
+
+ assert auth_cache_path() is None
+
+ assert legacy.read_text(encoding="utf-8") == '{"cookies": []}'
+
def test_call_sites_do_not_build_the_path_inline(self):
"""Invariant: the filename literal lives in one place. A second inline
copy is how the two call sites drifted apart in the first place.
diff --git a/selftests/test_cli_cleanup.py b/selftests/test_cli_cleanup.py
index 848c4d8a6..1e2470721 100644
--- a/selftests/test_cli_cleanup.py
+++ b/selftests/test_cli_cleanup.py
@@ -284,6 +284,28 @@ def _fail_interactive(**kwargs):
assert calls["headless"]["workbench_url"] == "https://wb.example.com"
assert calls["headless"]["username"] == "admin"
+ def test_no_cache_path_is_passed_through_to_auth(self, tmp_path, monkeypatch):
+ from vip.config import VIPConfig
+
+ self._patch_client_and_ui(monkeypatch)
+ monkeypatch.setattr(vip.cli.cleanup, "auth_cache_path", lambda: None)
+
+ calls = {}
+
+ def _fake_headless(**kwargs):
+ calls["headless"] = kwargs
+ return _fake_session(tmp_path)
+
+ monkeypatch.setattr(vip.cli.cleanup, "start_headless_auth", _fake_headless)
+
+ config = VIPConfig()
+ config.auth.username = "admin"
+ config.auth.password = "secret"
+
+ vip.cli._cleanup_workbench_sessions("https://wb.example.com", _make_args(), config)
+
+ assert calls["headless"]["cache_path"] is None
+
def test_uses_interactive_auth_when_no_credentials(self, tmp_path, monkeypatch):
from vip.config import VIPConfig
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 80dfd3be1..046933461 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -53,7 +53,7 @@ def _user_cache_root() -> Path:
return Path.home() / ".cache"
-def auth_cache_path() -> Path:
+def auth_cache_path() -> Path | None:
"""Path to the auth-session cache for the current invocation directory.
Single source of truth for both call sites: ``plugin/auth.py`` (``vip verify``)
@@ -71,9 +71,20 @@ def auth_cache_path() -> Path:
cwd is what users zip and share, and the cache holds a live session and API key
(#620). The directory is not created here; :func:`_save_auth_cache` does that, except
when :func:`_migrate_legacy_auth_cache` finds an old cache in cwd to move.
+
+ Returns ``None`` (caching is skipped, and a legacy cwd cache is left alone) when no
+ home directory can be determined and ``XDG_CACHE_HOME`` is unset.
"""
+ try:
+ cache_root = _user_cache_root()
+ except RuntimeError:
+ print(
+ ">>> Skipping auth cache: cannot determine a home directory; "
+ "set XDG_CACHE_HOME to enable it."
+ )
+ return None
key = hashlib.sha256(str(Path.cwd().resolve()).encode("utf-8")).hexdigest()[:16]
- path = _user_cache_root() / "vip" / "auth" / key / AUTH_CACHE_FILENAME
+ path = cache_root / "vip" / "auth" / key / AUTH_CACHE_FILENAME
_migrate_legacy_auth_cache(Path.cwd(), path)
return path
@@ -402,7 +413,7 @@ def refresh_auth_cache_from_storage_state(
cleanup path, where failing loudly would mask the test's own result.
"""
path = cache_path if cache_path is not None else auth_cache_path()
- if not path.exists():
+ if path is None or not path.exists():
return False
tmp: Path | None = None
From b0db2b2e5f28f0a1c38055bd21e912a0c43d13f5 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:09:56 -0700
Subject: [PATCH 06/14] fix(auth): treat an unreadable auth cache as a cache
miss
Refs #620
---
selftests/test_auth_cache.py | 48 ++++++++++++++++++++++++++++++++++++
src/vip/auth/browser.py | 6 ++---
src/vip/auth/cache.py | 23 +++++++++++------
3 files changed, 66 insertions(+), 11 deletions(-)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 551e20c92..779719861 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -136,6 +136,54 @@ def test_writes_both_resolved_and_requested_connect_urls(self, tmp_path):
assert meta["requested_connect_url"] == "https://c.example.com/dashboard"
+_NO_CHMOD = pytest.mark.skipif(
+ sys.platform == "win32" or (hasattr(os, "geteuid") and os.geteuid() == 0),
+ reason="needs POSIX permission bits that root does not honour",
+)
+
+
+@pytest.fixture
+def inaccessible_cache(tmp_path):
+ """A cache path inside a chmod-000 directory, restored on teardown."""
+ locked = tmp_path / "locked"
+ locked.mkdir()
+ locked.chmod(0)
+ try:
+ yield locked / ".vip-auth-cache.json"
+ finally:
+ locked.chmod(0o700)
+
+
+@_NO_CHMOD
+class TestInaccessibleCacheDir:
+ """An unreadable cache directory disables caching instead of raising."""
+
+ def test_load_returns_none(self, inaccessible_cache):
+ from vip.auth import _load_cached_auth
+
+ assert _load_cached_auth(inaccessible_cache) is None
+
+ def test_refresh_returns_false(self, inaccessible_cache):
+ from vip.auth import refresh_auth_cache_from_storage_state
+
+ assert refresh_auth_cache_from_storage_state({}, inaccessible_cache) is False
+
+ def test_cache_is_not_referenced(self, tmp_path, inaccessible_cache):
+ from vip.auth import InteractiveAuthSession
+
+ state = tmp_path / "state.json"
+ state.write_text('{"cookies": []}', encoding="utf-8")
+ session = InteractiveAuthSession(
+ storage_state_path=state,
+ api_key="K",
+ key_name="_vip_interactive_1",
+ _connect_url="https://c.example.com",
+ _cache_path=inaccessible_cache,
+ )
+
+ assert session._cache_references_this_key() is False
+
+
class TestLoadCachedAuth:
"""_load_cached_auth must refuse to reuse a cache that was minted
against different product URLs. The cache file lives one-per-
diff --git a/src/vip/auth/browser.py b/src/vip/auth/browser.py
index e63d4090b..4ac5041d9 100644
--- a/src/vip/auth/browser.py
+++ b/src/vip/auth/browser.py
@@ -181,12 +181,10 @@ def _cache_references_this_key(self) -> bool:
"""
if not self._cache_path or not self.api_key:
return False
- if not self._cache_path.exists():
- return False
meta_path = self._cache_path.with_suffix(".meta.json")
- if not meta_path.exists():
- return False
try:
+ if not self._cache_path.exists() or not meta_path.exists():
+ return False
# Validate the cache state file is parseable JSON. A corrupt
# state file would make Playwright's ``storage_state=`` load
# fail on the next run; treating it as a live reference would
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 046933461..f1a2915a0 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -247,22 +247,26 @@ def _load_cached_auth(
``None`` and every Workbench test skipped with a message that named no cause.
So when Workbench is requested we probe it before trusting the cache.
"""
- if not cache_path.exists():
+ meta_path = cache_path.with_suffix(".meta.json")
+ try:
+ if not cache_path.exists():
+ return None
+ # Check if the cache is less than 4 hours old.
+ age = time.time() - cache_path.stat().st_mtime
+ meta_exists = meta_path.exists()
+ except OSError:
+ # An inaccessible cache directory disables caching rather than aborting auth.
return None
-
- # Check if the cache is less than 4 hours old.
- age = time.time() - cache_path.stat().st_mtime
if age > 4 * 3600:
return None
# Read the companion metadata file if it exists.
- meta_path = cache_path.with_suffix(".meta.json")
api_key = None
key_name = ""
resolved_connect_url = ""
cached_request_connect_url = ""
cached_request_workbench_url = ""
- if meta_path.exists():
+ if meta_exists:
try:
meta = json.loads(meta_path.read_text(encoding="utf-8"))
api_key = meta.get("api_key")
@@ -413,7 +417,12 @@ def refresh_auth_cache_from_storage_state(
cleanup path, where failing loudly would mask the test's own result.
"""
path = cache_path if cache_path is not None else auth_cache_path()
- if path is None or not path.exists():
+ if path is None:
+ return False
+ try:
+ if not path.exists():
+ return False
+ except OSError:
return False
tmp: Path | None = None
From 6c66201ac98a09e1a5a970933046e6f45b9babb3 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 21 Oct 2026 12:10:40 -0700
Subject: [PATCH 07/14] fix(auth): leave no auth cache behind when a save fails
Refs #620
---
selftests/test_auth_cache.py | 42 ++++++++++++++++++++++++++++++++++++
src/vip/auth/cache.py | 6 ++++++
2 files changed, 48 insertions(+)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 779719861..18ff1704c 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -135,6 +135,48 @@ def test_writes_both_resolved_and_requested_connect_urls(self, tmp_path):
assert meta["connect_url"] == "https://c.example.com"
assert meta["requested_connect_url"] == "https://c.example.com/dashboard"
+ def _seed_old_pair(self, cache):
+ cache.write_text('{"cookies": [{"name": "old"}]}', encoding="utf-8")
+ cache.with_suffix(".meta.json").write_text('{"api_key": "OLD"}', encoding="utf-8")
+
+ def test_failed_meta_write_leaves_no_cache(self, tmp_path, monkeypatch):
+ from vip.auth import _save_auth_cache
+
+ session = self._make_session(tmp_path, connect_url="https://c.example.com", api_key="NEW")
+ cache = tmp_path / ".vip-auth-cache.json"
+ self._seed_old_pair(cache)
+ real_write_text = pathlib.Path.write_text
+
+ def fail_meta(self, *args, **kwargs):
+ if self.name.endswith(".meta.json"):
+ raise OSError(errno.ENOSPC, "No space left on device")
+ return real_write_text(self, *args, **kwargs)
+
+ monkeypatch.setattr(pathlib.Path, "write_text", fail_meta)
+
+ _save_auth_cache(session, cache)
+
+ assert not cache.exists()
+ assert not cache.with_suffix(".meta.json").exists()
+
+ def test_failed_state_write_leaves_no_cache(self, tmp_path, monkeypatch):
+ from vip.auth import _save_auth_cache
+ from vip.auth import cache as cache_module
+
+ session = self._make_session(tmp_path, connect_url="https://c.example.com", api_key="NEW")
+ cache = tmp_path / ".vip-auth-cache.json"
+ self._seed_old_pair(cache)
+
+ def fail(_state):
+ raise OSError(errno.ENOSPC, "No space left on device")
+
+ monkeypatch.setattr(cache_module, "_cacheable_storage_state", fail)
+
+ _save_auth_cache(session, cache)
+
+ assert not cache.exists()
+ assert not cache.with_suffix(".meta.json").exists()
+
_NO_CHMOD = pytest.mark.skipif(
sys.platform == "win32" or (hasattr(os, "geteuid") and os.geteuid() == 0),
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index f1a2915a0..624d9e773 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -479,6 +479,8 @@ def _save_auth_cache(session: InteractiveAuthSession, cache_path: Path) -> None:
}
try:
cache_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ # Drop any old meta first so it can never pair with a new or half-written state.
+ meta_path.unlink(missing_ok=True)
fd = os.open(cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
json.dump(_cacheable_storage_state(state), handle)
@@ -486,6 +488,10 @@ def _save_auth_cache(session: InteractiveAuthSession, cache_path: Path) -> None:
meta_path.write_text(json.dumps(meta), encoding="utf-8")
meta_path.chmod(0o600)
except OSError as exc:
+ # A failed save must leave no cache: a partial pair could be reused.
+ for leftover in (cache_path, meta_path):
+ with contextlib.suppress(OSError):
+ leftover.unlink(missing_ok=True)
print(
f">>> Skipping auth cache: cannot write {cache_path.parent} ({exc}); "
"next run will re-authenticate."
From ac1fb41058e71ef62898428053ae392ebc1c7f9d Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 14:39:19 -0800
Subject: [PATCH 08/14] fix(auth): move the legacy cache as a pair, prune
expired caches, document the location
---
AGENTS.md | 2 +-
README.md | 19 ++-
selftests/test_auth_cache.py | 247 +++++++++++++++++++++++++++++++---
selftests/test_cli_cleanup.py | 2 +-
src/vip/auth/__init__.py | 2 +
src/vip/auth/cache.py | 246 ++++++++++++++++++++++-----------
src/vip/cli/cleanup.py | 4 +-
src/vip/plugin/auth.py | 6 +-
website/src/pages/guide.astro | 23 ++++
9 files changed, 444 insertions(+), 107 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index d1e6e5b22..8053ad5e1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,7 +186,7 @@ Key principles:
| `src/vip/bundle/` | `vip bundle` internals: `summary.py` (allowlisted config summary and the secret list, with a selftest that fails on an unclassified config field), `archive.py` (allowlisted report files, encoded-form secret scan, atomic zip write), and `stamp.py` (the `_output/.vip-render.json` stamp that `vip report` writes, so that a bundle holds only rendered files made from its own `results.json`) |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`$XDG_CACHE_HOME`, `%LOCALAPPDATA%`, else `~/.cache`) in `vip/auth//`, never in cwd (returns `None` and skips caching when no home directory exists; the first resolve moves a legacy cwd cache there; both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`%LOCALAPPDATA%` on Windows, else `$XDG_CACHE_HOME` or `~/.cache`) in `vip/auth//`, never in cwd; it only computes the path (`None` when there is no home directory or cwd). `prepare_auth_cache()` is what the login call sites use (`plugin/auth.py` in the pytest controller and `cli/cleanup.py`; both must use it): it makes `vip/` and `vip/auth/` owner-only, moves a legacy cwd cache there as a state+meta pair (deleting it if the move fails), and prunes other directories' caches past `AUTH_CACHE_TTL_SECONDS`. `_load_cached_auth` treats a state file with no `.meta.json` as a miss and probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `BundleError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/README.md b/README.md
index b1e3edbf7..4bc0d7729 100644
--- a/README.md
+++ b/README.md
@@ -80,12 +80,23 @@ vip verify --config vip.toml --basic
`--interactive-auth` and `--headless-auth` cache a live session for 4 hours:
the identity provider (IdP), Connect, and Workbench cookies, plus a Connect
-API key that VIP creates. The cache lives in `~/.cache/vip/auth/` (`$XDG_CACHE_HOME/vip/auth/` if set, or
-`%LOCALAPPDATA%\vip\auth\` on Windows). Delete that directory to drop it. With no home
-directory and no `XDG_CACHE_HOME`, VIP skips the cache.
+API key that VIP creates. VIP keeps one cache for each directory you run it
+from, in a folder named after a hash of that directory:
+
+| Platform | Location |
+|---|---|
+| Linux, macOS | `$XDG_CACHE_HOME/vip/auth//`, or `~/.cache/vip/auth//` when `XDG_CACHE_HOME` is unset |
+| Windows | `%LOCALAPPDATA%\vip\auth\\` |
+
+Only your user can read these folders. Each `vip verify` or `vip cleanup`
+deletes caches older than 4 hours. VIP never reuses an expired cache, and the
+next login deletes the API keys of expired caches from Connect. To sign out now,
+delete the `vip/auth` folder. With no home directory and no `XDG_CACHE_HOME`,
+VIP skips the cache.
Earlier releases wrote `.vip-auth-cache.json` and `.vip-auth-cache.meta.json`
-into the working directory. The first run of this release moves them. Never
+into the working directory. The first `vip verify` or `vip cleanup` of this
+release moves them to the cache folder, or deletes them if it cannot. Never
share those files.
`vip.toml` can hold `api_key` and `password` values. Remove or redact them
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 18ff1704c..4d0865bf4 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -141,23 +141,51 @@ def _seed_old_pair(self, cache):
def test_failed_meta_write_leaves_no_cache(self, tmp_path, monkeypatch):
from vip.auth import _save_auth_cache
+ from vip.auth import cache as cache_module
session = self._make_session(tmp_path, connect_url="https://c.example.com", api_key="NEW")
cache = tmp_path / ".vip-auth-cache.json"
self._seed_old_pair(cache)
- real_write_text = pathlib.Path.write_text
+ real_write = cache_module._write_private_atomic
- def fail_meta(self, *args, **kwargs):
- if self.name.endswith(".meta.json"):
+ def fail_meta(path, payload):
+ if path.name.endswith(".meta.json"):
raise OSError(errno.ENOSPC, "No space left on device")
- return real_write_text(self, *args, **kwargs)
+ return real_write(path, payload)
+
+ monkeypatch.setattr(cache_module, "_write_private_atomic", fail_meta)
+
+ _save_auth_cache(session, cache)
+
+ assert not cache.exists()
+ assert not cache.with_suffix(".meta.json").exists()
+
+ def test_unserialisable_meta_leaves_no_cache(self, tmp_path, capsys):
+ from vip.auth import _save_auth_cache
- monkeypatch.setattr(pathlib.Path, "write_text", fail_meta)
+ session = self._make_session(tmp_path, connect_url="https://c.example.com", api_key="NEW")
+ session.key_name = object()
+ cache = tmp_path / ".vip-auth-cache.json"
+ self._seed_old_pair(cache)
_save_auth_cache(session, cache)
assert not cache.exists()
assert not cache.with_suffix(".meta.json").exists()
+ assert "Skipping auth cache" in capsys.readouterr().out
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permission bits")
+ def test_tightens_an_existing_cache_directory(self, tmp_path):
+ from vip.auth import _save_auth_cache
+
+ session = self._make_session(tmp_path, connect_url="", api_key=None)
+ cache = tmp_path / "loose" / ".vip-auth-cache.json"
+ cache.parent.mkdir(mode=0o755)
+ cache.parent.chmod(0o755)
+
+ _save_auth_cache(session, cache)
+
+ assert cache.parent.stat().st_mode & 0o777 == 0o700
def test_failed_state_write_leaves_no_cache(self, tmp_path, monkeypatch):
from vip.auth import _save_auth_cache
@@ -269,6 +297,14 @@ def test_reuses_cache_when_urls_match(self, tmp_path):
assert session is not None
assert session.api_key == "CACHED"
+ def test_state_without_meta_is_a_miss(self, tmp_path):
+ from vip.auth import _load_cached_auth
+
+ cache = self._write_cache(tmp_path, connect_url="https://c.example.com")
+ cache.with_suffix(".meta.json").unlink()
+
+ assert _load_cached_auth(cache, "https://c.example.com") is None
+
def test_rejects_cache_when_connect_url_differs(self, tmp_path, capsys):
from vip.auth import _load_cached_auth
@@ -738,7 +774,7 @@ def test_symlinked_cwd_resolves_to_the_same_cache(self, tmp_path, monkeypatch):
assert via_real == via_link
- @pytest.mark.skipif(sys.platform == "win32", reason="Windows ignores HOME and XDG_CACHE_HOME")
+ @pytest.mark.skipif(sys.platform == "win32", reason="Windows uses LOCALAPPDATA first")
def test_relative_xdg_cache_home_is_ignored(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
@@ -760,6 +796,47 @@ def test_windows_uses_localappdata(self, tmp_path, monkeypatch):
assert auth_cache_path().parent.parent == tmp_path / "lad" / "vip" / "auth"
+ def test_windows_prefers_localappdata_over_xdg_cache_home(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setattr(sys, "platform", "win32")
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "lad"))
+
+ assert auth_cache_path().parent.parent == tmp_path / "lad" / "vip" / "auth"
+
+ def test_macos_key_ignores_the_case_of_the_path(self, tmp_path, monkeypatch):
+ from vip.auth.cache import _cwd_key
+
+ monkeypatch.setattr(sys, "platform", "darwin")
+
+ assert _cwd_key(tmp_path / "Proj") == _cwd_key(tmp_path / "proj")
+
+ def test_deleted_cwd_returns_none(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path
+
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+
+ def gone():
+ raise FileNotFoundError(errno.ENOENT, "No such file or directory")
+
+ monkeypatch.setattr(pathlib.Path, "cwd", gone)
+
+ assert auth_cache_path() is None
+
+ def test_resolving_moves_nothing_and_prints_nothing(self, tmp_path, monkeypatch, capsys):
+ from vip.auth import auth_cache_path
+
+ TestLegacyAuthCacheMigration._legacy(tmp_path)
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+
+ auth_cache_path()
+
+ assert len(list(tmp_path.glob(".vip-auth-cache*"))) == 2
+ assert capsys.readouterr().out == ""
+
def test_resolving_creates_nothing_without_a_legacy_cache(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
@@ -782,24 +859,24 @@ def _raise():
monkeypatch.setattr(pathlib.Path, "home", _raise)
def test_no_home_directory_skips_the_cache(self, tmp_path, monkeypatch, capsys):
- from vip.auth import auth_cache_path
+ from vip.auth import prepare_auth_cache
self._no_home(tmp_path, monkeypatch)
before = set(tmp_path.iterdir())
- assert auth_cache_path() is None
+ assert prepare_auth_cache() is None
assert "Skipping auth cache" in capsys.readouterr().out
assert set(tmp_path.iterdir()) == before
def test_no_home_directory_leaves_legacy_cache_alone(self, tmp_path, monkeypatch):
- from vip.auth import auth_cache_path
+ from vip.auth import prepare_auth_cache
self._no_home(tmp_path, monkeypatch)
legacy = tmp_path / ".vip-auth-cache.json"
legacy.write_text('{"cookies": []}', encoding="utf-8")
- assert auth_cache_path() is None
+ assert prepare_auth_cache() is None
assert legacy.read_text(encoding="utf-8") == '{"cookies": []}'
@@ -912,7 +989,7 @@ def test_existing_dest_wins_and_legacy_is_deleted(self, tmp_path):
assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "NEWMETA"
assert list(work.glob(".vip-auth-cache*")) == []
- def test_failed_move_deletes_the_legacy_file_quietly(self, tmp_path, monkeypatch, caplog):
+ def test_failed_move_deletes_the_legacy_pair_and_warns(self, tmp_path, monkeypatch, caplog):
import shutil
from vip.auth.cache import _migrate_legacy_auth_cache
@@ -928,7 +1005,88 @@ def fail(*args, **kwargs):
_migrate_legacy_auth_cache(work, dest)
assert list(work.glob(".vip-auth-cache*")) == []
- assert caplog.records == []
+ assert not dest.exists()
+ warned = [r.getMessage() for r in caplog.records if r.levelname == "WARNING"]
+ assert len(warned) == 1
+ assert str(work) in warned[0]
+
+ def test_failed_meta_move_leaves_no_half_pair(self, tmp_path, monkeypatch):
+ import shutil
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ real_move = shutil.move
+
+ def fail_meta(src, dst):
+ if str(src).endswith(".meta.json"):
+ raise OSError(errno.ENOSPC, "No space left on device")
+ return real_move(src, dst)
+
+ monkeypatch.setattr(shutil, "move", fail_meta)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert not dest.exists()
+ assert not dest.with_suffix(".meta.json").exists()
+ assert list(work.glob(".vip-auth-cache*")) == []
+
+ def test_dest_state_without_meta_does_not_take_the_legacy_meta(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ dest.parent.mkdir(parents=True)
+ dest.write_text("NEW", encoding="utf-8")
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert dest.read_text(encoding="utf-8") == "NEW"
+ assert not dest.with_suffix(".meta.json").exists()
+ assert list(work.glob(".vip-auth-cache*")) == []
+
+ def test_stray_dest_meta_is_replaced_by_the_legacy_pair(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ dest.parent.mkdir(parents=True)
+ dest.with_suffix(".meta.json").write_text("STRAY", encoding="utf-8")
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert dest.read_text(encoding="utf-8") == "STATE"
+ assert dest.with_suffix(".meta.json").read_text(encoding="utf-8") == "META"
+
+ def test_legacy_meta_without_state_is_deleted_not_moved(self, tmp_path):
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ work.mkdir()
+ (work / ".vip-auth-cache.meta.json").write_text("META", encoding="utf-8")
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ assert not dest.with_suffix(".meta.json").exists()
+
+ def test_unreadable_legacy_dir_never_raises(self, tmp_path, monkeypatch):
+ from pathlib import Path
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+
+ def denied(self):
+ raise PermissionError(errno.EACCES, "denied")
+
+ monkeypatch.setattr(Path, "is_file", denied)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert not dest.exists()
def test_failed_move_and_failed_delete_warns_with_the_path(self, tmp_path, monkeypatch, caplog):
import shutil
@@ -1001,20 +1159,79 @@ def test_is_a_no_op_when_there_is_nothing_to_move(self, tmp_path):
assert not dest.parent.exists()
- def test_auth_cache_path_migrates_on_resolve(self, tmp_path, monkeypatch):
- from vip.auth import auth_cache_path
+ def test_prepare_auth_cache_migrates(self, tmp_path, monkeypatch):
+ from vip.auth import prepare_auth_cache
work = tmp_path / "work"
self._legacy(work)
monkeypatch.chdir(work)
monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
- path = auth_cache_path()
+ path = prepare_auth_cache()
assert list(work.glob(".vip-auth-cache*")) == []
assert path.read_text(encoding="utf-8") == "STATE"
+class TestPrepareAuthCache:
+ """prepare_auth_cache runs once per login: it tightens the cache tree and removes
+ expired caches other directories left behind.
+ """
+
+ @staticmethod
+ def _cache_dir(base, name, age):
+ directory = base / name
+ directory.mkdir(parents=True)
+ for f in (".vip-auth-cache.json", ".vip-auth-cache.meta.json"):
+ (directory / f).write_text("{}", encoding="utf-8")
+ old = time.time() - age
+ os.utime(directory / f, (old, old))
+ return directory
+
+ def test_prunes_expired_caches_from_other_directories(self, tmp_path, monkeypatch):
+ from vip.auth import prepare_auth_cache
+
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ base = tmp_path / "xdg" / "vip" / "auth"
+ expired = self._cache_dir(base, "0123456789abcdef", 5 * 3600)
+ fresh = self._cache_dir(base, "fedcba9876543210", 60)
+ not_ours = self._cache_dir(base, "notes", 5 * 3600)
+
+ path = prepare_auth_cache()
+
+ assert not expired.exists()
+ assert fresh.exists()
+ assert not_ours.exists()
+ assert path.parent.parent == base
+
+ def test_keeps_the_current_directory_cache_even_when_expired(self, tmp_path, monkeypatch):
+ from vip.auth import auth_cache_path, prepare_auth_cache
+
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ own = auth_cache_path().parent
+ self._cache_dir(own.parent, own.name, 5 * 3600)
+
+ prepare_auth_cache()
+
+ assert own.exists()
+
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permission bits")
+ def test_vip_and_auth_directories_are_owner_only(self, tmp_path, monkeypatch):
+ from vip.auth import prepare_auth_cache
+
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+ (tmp_path / "xdg" / "vip").mkdir(parents=True, mode=0o755)
+ (tmp_path / "xdg" / "vip").chmod(0o755)
+
+ prepare_auth_cache()
+
+ assert (tmp_path / "xdg" / "vip").stat().st_mode & 0o777 == 0o700
+ assert (tmp_path / "xdg" / "vip" / "auth").stat().st_mode & 0o777 == 0o700
+
+
class TestStaleCacheTriggersReauth:
"""End-to-end wiring: a dead cached session must fall through to the real
auth flow, not be handed to the tests. The helper-level tests above prove
diff --git a/selftests/test_cli_cleanup.py b/selftests/test_cli_cleanup.py
index d07a758e6..a7145c0c0 100644
--- a/selftests/test_cli_cleanup.py
+++ b/selftests/test_cli_cleanup.py
@@ -288,7 +288,7 @@ def test_no_cache_path_is_passed_through_to_auth(self, tmp_path, monkeypatch):
from vip.config import VIPConfig
self._patch_client_and_ui(monkeypatch)
- monkeypatch.setattr(vip.cli.cleanup, "auth_cache_path", lambda: None)
+ monkeypatch.setattr(vip.cli.cleanup, "prepare_auth_cache", lambda: None)
calls = {}
diff --git a/src/vip/auth/__init__.py b/src/vip/auth/__init__.py
index d62e841bd..2d3aee5bf 100644
--- a/src/vip/auth/__init__.py
+++ b/src/vip/auth/__init__.py
@@ -19,6 +19,7 @@
_ProbeResult,
_save_auth_cache,
auth_cache_path,
+ prepare_auth_cache,
refresh_auth_cache_from_storage_state,
)
from vip.auth.flows import start_headless_auth, start_interactive_auth
@@ -48,6 +49,7 @@
"_scheme_resolution_cache",
"_wait_for_product_redirect",
"auth_cache_path",
+ "prepare_auth_cache",
"authenticated_page",
"refresh_auth_cache_from_storage_state",
"resolve_url_scheme",
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 624d9e773..d6a192125 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -7,6 +7,7 @@
import json
import logging
import os
+import re
import shutil
import sys
import tempfile
@@ -32,6 +33,12 @@
AUTH_CACHE_FILENAME = ".vip-auth-cache.json"
+# A cached session older than this is never reused, and its directory is pruned.
+AUTH_CACHE_TTL_SECONDS = 4 * 3600
+
+# Per-directory cache folders are the first 16 hex digits of a SHA-256.
+_CACHE_DIR_NAME = re.compile(r"[0-9a-f]{16}")
+
# Cookies dropped before a storage state is written to the on-disk cache.
# Entra sets ESTSAUTHPERSISTENT even when "Stay signed in?" is answered No;
# the session ESTSAUTH cookie covers silent SSO for the cache's four-hour TTL.
@@ -39,26 +46,38 @@
def _user_cache_root() -> Path:
- """Per-user cache root: ``$XDG_CACHE_HOME``, ``%LOCALAPPDATA%`` on Windows, else ``~/.cache``.
+ """Per-user cache root: ``%LOCALAPPDATA%`` on Windows, else ``$XDG_CACHE_HOME`` or ``~/.cache``.
A relative ``XDG_CACHE_HOME`` is ignored, as the XDG spec requires. Creates nothing.
"""
- xdg = os.environ.get("XDG_CACHE_HOME")
- if xdg and Path(xdg).is_absolute():
- return Path(xdg)
if sys.platform == "win32":
local_app_data = os.environ.get("LOCALAPPDATA")
if local_app_data:
return Path(local_app_data)
+ xdg = os.environ.get("XDG_CACHE_HOME")
+ if xdg and Path(xdg).is_absolute():
+ return Path(xdg)
return Path.home() / ".cache"
+def _cwd_key(cwd: Path) -> str:
+ """Name of the cache directory for *cwd*.
+
+ The resolved path is case-folded on Windows and macOS, whose default filesystems
+ ignore case, so ``~/Proj`` and ``~/proj`` share one cache.
+ """
+ text = os.path.normcase(str(cwd.resolve()))
+ if sys.platform == "darwin":
+ text = text.casefold()
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+
def auth_cache_path() -> Path | None:
"""Path to the auth-session cache for the current invocation directory.
- Single source of truth for both call sites: ``plugin/auth.py`` (``vip verify``)
- and ``cli/cleanup.py`` (``vip cleanup --workbench-url``). They must agree, or
- ``cleanup`` cannot find the session ``verify`` just cached.
+ Single source of truth for the cache location. ``vip verify`` and ``vip cleanup``
+ reach it through :func:`prepare_auth_cache`; they must agree, or ``cleanup`` cannot
+ find the session ``verify`` just cached.
Keyed on the *invocation* directory rather than pytest's ``config.rootpath``.
For a repo checkout the two are the same, but for an installed VIP (``uv tool
@@ -69,49 +88,137 @@ def auth_cache_path() -> Path | None:
The cache lives under the user cache directory, not in the invocation directory:
cwd is what users zip and share, and the cache holds a live session and API key
- (#620). The directory is not created here; :func:`_save_auth_cache` does that, except
- when :func:`_migrate_legacy_auth_cache` finds an old cache in cwd to move.
+ (#620). This only computes the path; it touches no files and prints nothing.
- Returns ``None`` (caching is skipped, and a legacy cwd cache is left alone) when no
- home directory can be determined and ``XDG_CACHE_HOME`` is unset.
+ Returns ``None`` when there is no home directory (and ``XDG_CACHE_HOME`` is unset)
+ or the invocation directory no longer exists.
"""
try:
- cache_root = _user_cache_root()
- except RuntimeError:
+ return _user_cache_root() / "vip" / "auth" / _cwd_key(Path.cwd()) / AUTH_CACHE_FILENAME
+ except (RuntimeError, OSError):
+ return None
+
+
+def prepare_auth_cache() -> Path | None:
+ """Resolve the auth cache for a login, once per command.
+
+ Besides :func:`auth_cache_path`, this tightens ``vip/`` and ``vip/auth/`` to
+ owner-only, moves a cache an older VIP left in cwd, and deletes expired caches
+ that other directories left behind. Called by ``vip verify`` (the pytest
+ controller only, not each xdist worker) and ``vip cleanup``. Never raises.
+ """
+ path = auth_cache_path()
+ if path is None:
print(
- ">>> Skipping auth cache: cannot determine a home directory; "
- "set XDG_CACHE_HOME to enable it."
+ ">>> Skipping auth cache: cannot determine a home directory or the working "
+ "directory; set XDG_CACHE_HOME to enable it."
)
return None
- key = hashlib.sha256(str(Path.cwd().resolve()).encode("utf-8")).hexdigest()[:16]
- path = cache_root / "vip" / "auth" / key / AUTH_CACHE_FILENAME
- _migrate_legacy_auth_cache(Path.cwd(), path)
+ base = path.parent.parent
+ with contextlib.suppress(OSError):
+ for directory in (base.parent, base):
+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+ directory.chmod(0o700)
+ with contextlib.suppress(OSError):
+ _migrate_legacy_auth_cache(Path.cwd(), path)
+ _prune_expired_auth_caches(base, keep=path.parent)
return path
-def _migrate_legacy_auth_cache(legacy_dir: Path, dest: Path) -> None:
- """Move caches an older VIP wrote into ``legacy_dir`` to ``dest``, never raising.
+def _make_private_dir(directory: Path) -> None:
+ """Create *directory* owner-only, tightening it if it already exists."""
+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+ directory.chmod(0o700)
- A live session and API key must not stay in a directory users zip and share (#620),
- so a file that cannot be moved is deleted. Idempotent: with nothing in ``legacy_dir``
- it does nothing.
+
+def _prune_expired_auth_caches(base: Path, keep: Path) -> None:
+ """Delete cache directories under *base* whose newest file is past the TTL, never raising.
+
+ An expired cache is never reused, so it only keeps cookies and an API key on disk.
+ The key itself is removed by the stale-key sweep the next login runs on Connect.
"""
- for target in (dest, dest.with_suffix(".meta.json")):
- legacy = legacy_dir / target.name
- if legacy == target or not legacy.is_file():
+ now = time.time()
+ try:
+ entries = list(base.iterdir())
+ except OSError:
+ return
+ for directory in entries:
+ if directory == keep or not _CACHE_DIR_NAME.fullmatch(directory.name):
continue
try:
- if not target.exists():
- target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
- shutil.move(str(legacy), str(target))
- target.chmod(0o600)
- else:
- legacy.unlink(missing_ok=True)
+ newest = max((f.stat().st_mtime for f in directory.iterdir()), default=0.0)
+ if now - newest > AUTH_CACHE_TTL_SECONDS:
+ shutil.rmtree(directory)
+ except OSError as exc:
+ logger.debug("Could not prune expired auth cache %s: %s", directory, exc)
+
+
+def _migrate_legacy_auth_cache(legacy_dir: Path, dest: Path) -> None:
+ """Move the cache pair an older VIP wrote into ``legacy_dir`` to ``dest``, never raising.
+
+ The state and meta files move together or not at all: a meta next to another
+ session's state would hand out the wrong API key. When ``dest`` already holds a
+ cache, or the move fails, the legacy files are deleted instead, because a live session
+ must not stay in a directory users zip and share (#620). The orphaned Connect key is
+ removed by the next login's stale-key sweep.
+ """
+ meta_dest = dest.with_suffix(".meta.json")
+ legacy_state = legacy_dir / dest.name
+ legacy_meta = legacy_dir / meta_dest.name
+ try:
+ if legacy_state == dest or not (legacy_state.is_file() or legacy_meta.is_file()):
+ return
+ move = legacy_state.is_file() and not dest.exists()
+ except OSError:
+ return
+ if move:
+ try:
+ _make_private_dir(dest.parent)
+ # A meta with no state belongs to no session; it must not pair with the moved one.
+ meta_dest.unlink(missing_ok=True)
+ shutil.move(str(legacy_state), str(dest))
+ dest.chmod(0o600)
+ if legacy_meta.is_file():
+ shutil.move(str(legacy_meta), str(meta_dest))
+ meta_dest.chmod(0o600)
+ return
+ except FileNotFoundError:
+ # Another VIP run in this directory moved the state first; its copy stands.
+ pass
+ except OSError as exc:
+ for moved in (dest, meta_dest):
+ with contextlib.suppress(OSError):
+ moved.unlink(missing_ok=True)
+ logger.warning(
+ "Could not move the auth cache out of %s (%s); deleting it instead. "
+ "The next run signs in again.",
+ legacy_dir,
+ exc,
+ )
+ for legacy in (legacy_state, legacy_meta):
+ try:
+ legacy.unlink(missing_ok=True)
except OSError:
- try:
- legacy.unlink(missing_ok=True)
- except OSError:
- logger.warning("Could not remove legacy auth cache %s; delete it by hand.", legacy)
+ logger.warning("Could not remove legacy auth cache %s; delete it by hand.", legacy)
+
+
+def _write_private_atomic(path: Path, payload: str) -> None:
+ """Write *payload* to *path* owner-only, via a temp file and rename.
+
+ The temp file sits in the same directory so the rename is atomic, and a concurrent
+ reader never sees a half-written file.
+ """
+ fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=".vip-auth-cache-")
+ tmp = Path(tmp_name)
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(payload)
+ tmp.chmod(0o600)
+ tmp.replace(path)
+ except BaseException:
+ with contextlib.suppress(OSError):
+ tmp.unlink(missing_ok=True)
+ raise
def _cookies_from_storage_state(storage_state_path: Path) -> httpx.Cookies:
@@ -257,31 +364,23 @@ def _load_cached_auth(
except OSError:
# An inaccessible cache directory disables caching rather than aborting auth.
return None
- if age > 4 * 3600:
+ if age > AUTH_CACHE_TTL_SECONDS:
+ return None
+ # A state with no meta is a save in progress or a half-finished one; its key is unknown.
+ if not meta_exists:
return None
- # Read the companion metadata file if it exists.
- api_key = None
- key_name = ""
- resolved_connect_url = ""
- cached_request_connect_url = ""
- cached_request_workbench_url = ""
- if meta_exists:
- try:
- meta = json.loads(meta_path.read_text(encoding="utf-8"))
- api_key = meta.get("api_key")
- key_name = meta.get("key_name", "")
- resolved_connect_url = meta.get("connect_url", "")
- # Older caches (pre-fix) only stored the resolved URL. Fall
- # back to it so a stale cache still matches when the
- # resolved and requested forms are identical (no sub-path
- # rewrite happened).
- cached_request_connect_url = (
- meta.get("requested_connect_url", "") or resolved_connect_url
- )
- cached_request_workbench_url = meta.get("workbench_url", "")
- except (OSError, ValueError, AttributeError):
- pass
+ try:
+ meta = json.loads(meta_path.read_text(encoding="utf-8"))
+ api_key = meta.get("api_key")
+ key_name = meta.get("key_name", "")
+ resolved_connect_url = meta.get("connect_url", "")
+ # Older caches only stored the resolved URL. Fall back to it so a stale cache
+ # still matches when the resolved and requested forms are identical.
+ cached_request_connect_url = meta.get("requested_connect_url", "") or resolved_connect_url
+ cached_request_workbench_url = meta.get("workbench_url", "")
+ except (OSError, ValueError, AttributeError):
+ return None
# Match against the *requested* Connect URL so that
# ``_resolve_connect_api_base`` rewriting the dashboard URL to a
@@ -425,23 +524,11 @@ def refresh_auth_cache_from_storage_state(
except OSError:
return False
- tmp: Path | None = None
try:
- payload = json.dumps(_cacheable_storage_state(storage_state))
- # Same directory so the rename stays on one filesystem (and therefore
- # atomic); mkstemp creates it 0600 already.
- fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=".vip-auth-cache-")
- tmp = Path(tmp_name)
- with os.fdopen(fd, "w", encoding="utf-8") as handle:
- handle.write(payload)
- tmp.chmod(0o600)
- tmp.replace(path)
+ _write_private_atomic(path, json.dumps(_cacheable_storage_state(storage_state)))
return True
except Exception as exc: # noqa: BLE001 -- cleanup path; never raises, see docstring
logger.debug("Could not refresh the auth cache at %s: %s", path, exc)
- if tmp is not None and tmp.exists():
- with contextlib.suppress(OSError):
- tmp.unlink()
return False
@@ -478,16 +565,13 @@ def _save_auth_cache(session: InteractiveAuthSession, cache_path: Path) -> None:
"workbench_url": session._workbench_url,
}
try:
- cache_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
- # Drop any old meta first so it can never pair with a new or half-written state.
+ _make_private_dir(cache_path.parent)
+ # Drop the old meta first so it never pairs with the new state. Until the new
+ # meta lands, a concurrent _load_cached_auth sees no meta and treats it as a miss.
meta_path.unlink(missing_ok=True)
- fd = os.open(cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
- with os.fdopen(fd, "w", encoding="utf-8") as handle:
- json.dump(_cacheable_storage_state(state), handle)
- cache_path.chmod(0o600)
- meta_path.write_text(json.dumps(meta), encoding="utf-8")
- meta_path.chmod(0o600)
- except OSError as exc:
+ _write_private_atomic(cache_path, json.dumps(_cacheable_storage_state(state)))
+ _write_private_atomic(meta_path, json.dumps(meta))
+ except (OSError, TypeError, ValueError) as exc:
# A failed save must leave no cache: a partial pair could be reused.
for leftover in (cache_path, meta_path):
with contextlib.suppress(OSError):
diff --git a/src/vip/cli/cleanup.py b/src/vip/cli/cleanup.py
index 99f86f589..a71e227fb 100644
--- a/src/vip/cli/cleanup.py
+++ b/src/vip/cli/cleanup.py
@@ -10,8 +10,8 @@
from vip.auth import (
AuthConfigError,
- auth_cache_path,
authenticated_page,
+ prepare_auth_cache,
resolve_url_scheme,
start_headless_auth,
start_interactive_auth,
@@ -95,7 +95,7 @@ def _cleanup_workbench_sessions(
proxy = config.proxy
# Same helper plugin/auth.py uses, so this finds the session a prior `vip verify`
# from this directory cached.
- cache_path = auth_cache_path()
+ cache_path = prepare_auth_cache()
username = config.auth.username
password = config.auth.password
diff --git a/src/vip/plugin/auth.py b/src/vip/plugin/auth.py
index 50a4aec7e..b87768b31 100644
--- a/src/vip/plugin/auth.py
+++ b/src/vip/plugin/auth.py
@@ -10,7 +10,7 @@
from vip.auth import (
AuthConfigError,
InteractiveAuthSession,
- auth_cache_path,
+ prepare_auth_cache,
start_headless_auth,
start_interactive_auth,
)
@@ -53,7 +53,7 @@ def _configure_auth(config: pytest.Config, vip_cfg: VIPConfig) -> None:
stacklevel=1,
)
else:
- cache_path = auth_cache_path()
+ cache_path = prepare_auth_cache()
try:
session = start_interactive_auth(
connect_url=connect_url,
@@ -104,7 +104,7 @@ def _configure_auth(config: pytest.Config, vip_cfg: VIPConfig) -> None:
stacklevel=1,
)
else:
- cache_path = auth_cache_path()
+ cache_path = prepare_auth_cache()
try:
session = start_headless_auth(
connect_url=connect_url,
diff --git a/website/src/pages/guide.astro b/website/src/pages/guide.astro
index 80153567a..846c8c67c 100644
--- a/website/src/pages/guide.astro
+++ b/website/src/pages/guide.astro
@@ -102,6 +102,29 @@ import "../styles/docs.css";
VIP_TEST_PASSWORD.
+ Where the saved session lives
+
+ Interactive and headless auth save the browser session and the
+ minted Connect API key for 4 hours, so the next run from the same
+ directory skips the login. VIP keeps one cache for each directory
+ you run it from, outside that directory, so a zipped or shared VIP
+ folder never contains it:
+
+
+ - Linux and macOS:
$XDG_CACHE_HOME/vip/auth/, or ~/.cache/vip/auth/ when XDG_CACHE_HOME is unset
+ - Windows:
%LOCALAPPDATA%\vip\auth\
+
+
+ Only your user can read these folders. Each vip verify
+ or vip cleanup deletes caches older than 4 hours, and
+ the next login removes their API keys from Connect. To sign out
+ sooner, delete the vip/auth folder. Older releases
+ saved .vip-auth-cache.json and
+ .vip-auth-cache.meta.json in the working directory;
+ the first run of a newer release moves them, or deletes them if it
+ cannot.
+
+
API-key-only auth
If you only have an API key and no browser credentials, use
From 7b031f10e54d0383318331424d6580e5cce52c7a Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 14:43:28 -0800
Subject: [PATCH 09/14] test: clear LOCALAPPDATA so auth cache selftests stay
in tmp_path on Windows
---
selftests/conftest.py | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/selftests/conftest.py b/selftests/conftest.py
index f96472077..1865fa733 100644
--- a/selftests/conftest.py
+++ b/selftests/conftest.py
@@ -52,6 +52,17 @@ def _restore_auth_entrypoints():
setattr(_auth, name, func)
+@pytest.fixture(autouse=True)
+def _no_ambient_localappdata(monkeypatch):
+ """Clear ``LOCALAPPDATA`` so the auth cache root follows ``XDG_CACHE_HOME`` in every selftest.
+
+ On Windows ``LOCALAPPDATA`` comes first, so a test that points ``XDG_CACHE_HOME`` at
+ ``tmp_path`` would otherwise read, write and prune the runner's real cache. Tests
+ about the Windows root set it themselves.
+ """
+ monkeypatch.delenv("LOCALAPPDATA", raising=False)
+
+
@pytest.fixture(autouse=True)
def _no_ambient_proxy(monkeypatch):
"""Clear proxy environment variables for every selftest.
From 43269880aa1e4aaa092158741ae8e7c75b8226af Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 14:53:01 -0800
Subject: [PATCH 10/14] fix(auth): tidy the auth cache on every run and delete
legacy files when the cache dir is unreachable
---
AGENTS.md | 2 +-
selftests/conftest.py | 12 +++++++-----
selftests/test_auth_cache.py | 23 +++++++++++++++++++++++
selftests/test_cli_cleanup.py | 27 ++++++++++++++++++++++++++-
selftests/test_plugin.py | 20 ++++++++++++++++++++
src/vip/auth/cache.py | 25 ++++++++++++++++++++-----
src/vip/cli/cleanup.py | 3 +++
src/vip/plugin/auth.py | 11 ++++++++---
8 files changed, 108 insertions(+), 15 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 8053ad5e1..a8a6536e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,7 +186,7 @@ Key principles:
| `src/vip/bundle/` | `vip bundle` internals: `summary.py` (allowlisted config summary and the secret list, with a selftest that fails on an unclassified config field), `archive.py` (allowlisted report files, encoded-form secret scan, atomic zip write), and `stamp.py` (the `_output/.vip-render.json` stamp that `vip report` writes, so that a bundle holds only rendered files made from its own `results.json`) |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`%LOCALAPPDATA%` on Windows, else `$XDG_CACHE_HOME` or `~/.cache`) in `vip/auth//`, never in cwd; it only computes the path (`None` when there is no home directory or cwd). `prepare_auth_cache()` is what the login call sites use (`plugin/auth.py` in the pytest controller and `cli/cleanup.py`; both must use it): it makes `vip/` and `vip/auth/` owner-only, moves a legacy cwd cache there as a state+meta pair (deleting it if the move fails), and prunes other directories' caches past `AUTH_CACHE_TTL_SECONDS`. `_load_cached_auth` treats a state file with no `.meta.json` as a miss and probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`%LOCALAPPDATA%` on Windows, else `$XDG_CACHE_HOME` or `~/.cache`) in `vip/auth//`, never in cwd; it only computes the path (`None` when there is no home directory or cwd). `prepare_auth_cache()` runs on every `vip verify` (in `plugin/auth.py`, pytest controller only) and every `vip cleanup` (`cli/cleanup.py`), with or without a browser login, and both login paths must take the cache path from it: it makes `vip/` and `vip/auth/` owner-only, moves a legacy cwd cache there as a state+meta pair (deleting it if the move fails), and prunes other directories' caches past `AUTH_CACHE_TTL_SECONDS`. `_load_cached_auth` treats a state file with no `.meta.json` as a miss and probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `BundleError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/selftests/conftest.py b/selftests/conftest.py
index 1865fa733..42ba59842 100644
--- a/selftests/conftest.py
+++ b/selftests/conftest.py
@@ -53,14 +53,16 @@ def _restore_auth_entrypoints():
@pytest.fixture(autouse=True)
-def _no_ambient_localappdata(monkeypatch):
- """Clear ``LOCALAPPDATA`` so the auth cache root follows ``XDG_CACHE_HOME`` in every selftest.
+def _isolated_auth_cache_root(monkeypatch, tmp_path_factory):
+ """Point the auth cache root at a temp directory for every selftest.
- On Windows ``LOCALAPPDATA`` comes first, so a test that points ``XDG_CACHE_HOME`` at
- ``tmp_path`` would otherwise read, write and prune the runner's real cache. Tests
- about the Windows root set it themselves.
+ ``vip verify`` and ``vip cleanup`` tidy the real cache (migrate, prune, chmod) on
+ every run, so a selftest must never resolve the user's own ``~/.cache``. On Windows
+ ``LOCALAPPDATA`` comes before ``XDG_CACHE_HOME``, so it is cleared too. Tests about
+ the cache root set their own values with ``monkeypatch``.
"""
monkeypatch.delenv("LOCALAPPDATA", raising=False)
+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path_factory.mktemp("xdg-cache")))
@pytest.fixture(autouse=True)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index 4d0865bf4..f47d2da4b 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -1071,6 +1071,29 @@ def test_legacy_meta_without_state_is_deleted_not_moved(self, tmp_path):
assert list(work.glob(".vip-auth-cache*")) == []
assert not dest.with_suffix(".meta.json").exists()
+ def test_unreachable_dest_still_deletes_the_legacy_pair(self, tmp_path, monkeypatch, caplog):
+ from pathlib import Path
+
+ from vip.auth.cache import _migrate_legacy_auth_cache
+
+ work, dest = tmp_path / "work", self._dest(tmp_path)
+ self._legacy(work)
+ real_exists = Path.exists
+
+ def denied(self, *args, **kwargs):
+ if self == dest:
+ raise PermissionError(errno.EACCES, "denied")
+ return real_exists(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "exists", denied)
+
+ _migrate_legacy_auth_cache(work, dest)
+
+ assert list(work.glob(".vip-auth-cache*")) == []
+ warned = [r.getMessage() for r in caplog.records if r.levelname == "WARNING"]
+ assert len(warned) == 1
+ assert str(work) in warned[0]
+
def test_unreadable_legacy_dir_never_raises(self, tmp_path, monkeypatch):
from pathlib import Path
diff --git a/selftests/test_cli_cleanup.py b/selftests/test_cli_cleanup.py
index a7145c0c0..acf12c112 100644
--- a/selftests/test_cli_cleanup.py
+++ b/selftests/test_cli_cleanup.py
@@ -134,6 +134,31 @@ def _fail(*a, **k):
assert "Deleted 3 VIP test content item(s)" in out
assert "Cleanup completed successfully" in out
+ def test_connect_only_still_moves_a_legacy_auth_cache(self, tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("VIP_CONFIG", raising=False)
+ (tmp_path / ".vip-auth-cache.json").write_text("{}", encoding="utf-8")
+ (tmp_path / ".vip-auth-cache.meta.json").write_text("{}", encoding="utf-8")
+
+ class _FakeConnectClient:
+ def __init__(self, *a, **k):
+ pass
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def cleanup_vip_content(self):
+ return 0
+
+ monkeypatch.setattr("vip.cli.cleanup.ConnectClient", _FakeConnectClient)
+
+ vip.cli.run_cleanup(_make_args(connect_url="https://c.example.com"))
+
+ assert list(tmp_path.glob(".vip-auth-cache*")) == []
+
def test_workbench_only_does_not_touch_connect(self, tmp_path, monkeypatch):
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("VIP_CONFIG", raising=False)
@@ -288,7 +313,7 @@ def test_no_cache_path_is_passed_through_to_auth(self, tmp_path, monkeypatch):
from vip.config import VIPConfig
self._patch_client_and_ui(monkeypatch)
- monkeypatch.setattr(vip.cli.cleanup, "prepare_auth_cache", lambda: None)
+ monkeypatch.setattr(vip.cli.cleanup, "prepare_auth_cache", lambda **_: None)
calls = {}
diff --git a/selftests/test_plugin.py b/selftests/test_plugin.py
index 6ecc52570..d76d13669 100644
--- a/selftests/test_plugin.py
+++ b/selftests/test_plugin.py
@@ -541,6 +541,26 @@ def test_headless_auth_option_registered(self, pytester):
class TestHeadlessAuthFixture:
+ def test_run_without_browser_auth_moves_a_legacy_auth_cache(self, pytester):
+ """Every controller run tidies the auth cache, so a legacy cwd cache moves even
+ when no browser login happens.
+ """
+ pytester.makefile(".toml", vip='[general]\ndeployment_name = "Selftest"')
+ (pytester.path / ".vip-auth-cache.json").write_text("{}", encoding="utf-8")
+ (pytester.path / ".vip-auth-cache.meta.json").write_text("{}", encoding="utf-8")
+ pytester.makepyfile(
+ """
+ def test_placeholder():
+ assert True
+ """
+ )
+
+ result = pytester.runpytest_subprocess("--vip-config=vip.toml")
+
+ result.assert_outcomes(passed=1)
+ assert list(pytester.path.glob(".vip-auth-cache*")) == []
+ assert "Skipping auth cache" not in result.stdout.str()
+
def test_headless_auth_skipped_when_no_auth_products(self, pytester):
"""--headless-auth skips the browser flow when no auth-requiring products are enabled.
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index d6a192125..d644378dd 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -99,16 +99,20 @@ def auth_cache_path() -> Path | None:
return None
-def prepare_auth_cache() -> Path | None:
- """Resolve the auth cache for a login, once per command.
+def prepare_auth_cache(*, announce_skip: bool = True) -> Path | None:
+ """Resolve the auth cache and tidy it, once per command.
Besides :func:`auth_cache_path`, this tightens ``vip/`` and ``vip/auth/`` to
owner-only, moves a cache an older VIP left in cwd, and deletes expired caches
- that other directories left behind. Called by ``vip verify`` (the pytest
- controller only, not each xdist worker) and ``vip cleanup``. Never raises.
+ that other directories left behind. ``vip verify`` (the pytest controller only,
+ not each xdist worker) and ``vip cleanup`` call it on every run, logging in or not,
+ so an upgrade never leaves a legacy cache in cwd. *announce_skip* prints why there
+ is no cache; pass False on runs that would not use one. Never raises.
"""
path = auth_cache_path()
if path is None:
+ if not announce_skip:
+ return None
print(
">>> Skipping auth cache: cannot determine a home directory or the working "
"directory; set XDG_CACHE_HOME to enable it."
@@ -168,9 +172,20 @@ def _migrate_legacy_auth_cache(legacy_dir: Path, dest: Path) -> None:
try:
if legacy_state == dest or not (legacy_state.is_file() or legacy_meta.is_file()):
return
- move = legacy_state.is_file() and not dest.exists()
+ has_state = legacy_state.is_file()
except OSError:
return
+ try:
+ move = has_state and not dest.exists()
+ except OSError as exc:
+ move = False
+ logger.warning(
+ "Cannot reach the auth cache at %s (%s); deleting the auth cache in %s instead. "
+ "The next run signs in again.",
+ dest.parent,
+ exc,
+ legacy_dir,
+ )
if move:
try:
_make_private_dir(dest.parent)
diff --git a/src/vip/cli/cleanup.py b/src/vip/cli/cleanup.py
index a71e227fb..f0415dd2a 100644
--- a/src/vip/cli/cleanup.py
+++ b/src/vip/cli/cleanup.py
@@ -244,6 +244,9 @@ def run_cleanup(args: argparse.Namespace) -> None:
# explicit `vip cleanup --connect-url ...` with no vip.toml must not emit a
# "Config file not found" warning (env-based credentials still apply).
config = _load_cleanup_config(args)
+ # Tidy the auth cache on every run, so an upgrade moves a legacy cache out of cwd
+ # even when no browser login follows (Connect only, or a Workbench API token).
+ prepare_auth_cache(announce_skip=False)
# A CLI flag wins over vip.toml. Wrapping the CLI arg in ProductConfig
# routes it through the same _normalize_url a bare hostname gets from
diff --git a/src/vip/plugin/auth.py b/src/vip/plugin/auth.py
index b87768b31..30b978d4d 100644
--- a/src/vip/plugin/auth.py
+++ b/src/vip/plugin/auth.py
@@ -39,7 +39,14 @@ def _configure_auth(config: pytest.Config, vip_cfg: VIPConfig) -> None:
# still mirror the controller's auth mode so the auth_mode fixture
# matches a non-xdist run.
config.stash[_auth_mode_key] = config.workerinput["vip_auth_mode"]
- elif config.getoption("--interactive-auth"):
+ return
+
+ # Tidy the auth cache on every controller run, not only browser logins, so an
+ # upgrade moves a legacy cache out of cwd even under --api-auth.
+ browser_auth = config.getoption("--interactive-auth") or config.getoption("--headless-auth")
+ cache_path = prepare_auth_cache(announce_skip=bool(browser_auth))
+
+ if config.getoption("--interactive-auth"):
config.stash[_auth_mode_key] = "interactive"
connect_url = vip_cfg.connect.url if vip_cfg.connect.is_configured else None
wb_url = vip_cfg.workbench.url if vip_cfg.workbench.is_configured else None
@@ -53,7 +60,6 @@ def _configure_auth(config: pytest.Config, vip_cfg: VIPConfig) -> None:
stacklevel=1,
)
else:
- cache_path = prepare_auth_cache()
try:
session = start_interactive_auth(
connect_url=connect_url,
@@ -104,7 +110,6 @@ def _configure_auth(config: pytest.Config, vip_cfg: VIPConfig) -> None:
stacklevel=1,
)
else:
- cache_path = prepare_auth_cache()
try:
session = start_headless_auth(
connect_url=connect_url,
From b8d251830ed809079d5f6510900ef148e79e0a24 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 15:04:31 -0800
Subject: [PATCH 11/14] Implement pytest hooks for auth cache management
Add pytest hooks to manage authentication cache during tests.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
selftests/conftest.py | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/selftests/conftest.py b/selftests/conftest.py
index 42ba59842..38769a04d 100644
--- a/selftests/conftest.py
+++ b/selftests/conftest.py
@@ -52,6 +52,24 @@ def _restore_auth_entrypoints():
setattr(_auth, name, func)
+_auth_cache_setup_patch_key = pytest.StashKey[pytest.MonkeyPatch]()
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_configure(config):
+ """Keep outer-session configuration away from the user's credential files."""
+ patch = pytest.MonkeyPatch()
+ config.stash[_auth_cache_setup_patch_key] = patch
+ config.add_cleanup(patch.undo)
+ patch.setattr("vip.plugin.auth.prepare_auth_cache", lambda **_: None)
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_sessionstart(session):
+ """Restore cache preparation before selftests and nested pytest runs."""
+ session.config.stash[_auth_cache_setup_patch_key].undo()
+
+
@pytest.fixture(autouse=True)
def _isolated_auth_cache_root(monkeypatch, tmp_path_factory):
"""Point the auth cache root at a temp directory for every selftest.
From b603dbf6ab296fbbd220ad6a88ee671966cc79a1 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 15:04:40 -0800
Subject: [PATCH 12/14] Change hash generation to use os.fsencode
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
src/vip/auth/cache.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index d644378dd..0be9731d2 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -69,7 +69,7 @@ def _cwd_key(cwd: Path) -> str:
text = os.path.normcase(str(cwd.resolve()))
if sys.platform == "darwin":
text = text.casefold()
- return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+ return hashlib.sha256(os.fsencode(text)).hexdigest()[:16]
def auth_cache_path() -> Path | None:
From 0b74e5f5f146d7ff89e567efa3b163e91afe4ac9 Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 15:05:57 -0800
Subject: [PATCH 13/14] test(auth): cover the cache key for a non-UTF-8
directory name
---
selftests/test_auth_cache.py | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index f47d2da4b..ddd1f6096 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -813,6 +813,14 @@ def test_macos_key_ignores_the_case_of_the_path(self, tmp_path, monkeypatch):
assert _cwd_key(tmp_path / "Proj") == _cwd_key(tmp_path / "proj")
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX paths can hold non-UTF-8 bytes")
+ def test_non_utf8_directory_name_still_gets_a_key(self, tmp_path):
+ from vip.auth.cache import _cwd_key
+
+ key = _cwd_key(tmp_path / os.fsdecode(b"caf\xe9"))
+
+ assert len(key) == 16
+
def test_deleted_cwd_returns_none(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
From f0ede10646cab1ed5671a1c2498a3230c20f761a Mon Sep 17 00:00:00 2001
From: Ian Flores Siaca <18703558+ian-flores@users.noreply.github.com>
Date: Wed, 18 Nov 2026 15:15:20 -0800
Subject: [PATCH 14/14] fix(auth): prune other directories' caches only after a
day
---
AGENTS.md | 2 +-
README.md | 5 +++--
selftests/test_auth_cache.py | 7 +++++--
src/vip/auth/cache.py | 15 ++++++++++-----
website/src/pages/guide.astro | 5 +++--
5 files changed, 22 insertions(+), 12 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index a8a6536e2..730bd1650 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,7 +186,7 @@ Key principles:
| `src/vip/bundle/` | `vip bundle` internals: `summary.py` (allowlisted config summary and the secret list, with a selftest that fails on an unclassified config field), `archive.py` (allowlisted report files, encoded-form secret scan, atomic zip write), and `stamp.py` (the `_output/.vip-render.json` stamp that `vip report` writes, so that a bundle holds only rendered files made from its own `results.json`) |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
-| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`%LOCALAPPDATA%` on Windows, else `$XDG_CACHE_HOME` or `~/.cache`) in `vip/auth//`, never in cwd; it only computes the path (`None` when there is no home directory or cwd). `prepare_auth_cache()` runs on every `vip verify` (in `plugin/auth.py`, pytest controller only) and every `vip cleanup` (`cli/cleanup.py`), with or without a browser login, and both login paths must take the cache path from it: it makes `vip/` and `vip/auth/` owner-only, moves a legacy cwd cache there as a state+meta pair (deleting it if the move fails), and prunes other directories' caches past `AUTH_CACHE_TTL_SECONDS`. `_load_cached_auth` treats a state file with no `.meta.json` as a miss and probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
+| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location, under the user cache dir (`%LOCALAPPDATA%` on Windows, else `$XDG_CACHE_HOME` or `~/.cache`) in `vip/auth//`, never in cwd; it only computes the path (`None` when there is no home directory or cwd). `prepare_auth_cache()` runs on every `vip verify` (in `plugin/auth.py`, pytest controller only) and every `vip cleanup` (`cli/cleanup.py`), with or without a browser login, and both login paths must take the cache path from it: it makes `vip/` and `vip/auth/` owner-only, moves a legacy cwd cache there as a state+meta pair (deleting it if the move fails), and prunes other directories' caches past `AUTH_CACHE_PRUNE_AFTER_SECONDS` (a day, so a run that reused a cache just inside the 4-hour `AUTH_CACHE_TTL_SECONDS` keeps its storage state). `_load_cached_auth` treats a state file with no `.meta.json` as a miss and probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `BundleError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
diff --git a/README.md b/README.md
index 4bc0d7729..8b399c3bb 100644
--- a/README.md
+++ b/README.md
@@ -89,8 +89,9 @@ from, in a folder named after a hash of that directory:
| Windows | `%LOCALAPPDATA%\vip\auth\\` |
Only your user can read these folders. Each `vip verify` or `vip cleanup`
-deletes caches older than 4 hours. VIP never reuses an expired cache, and the
-next login deletes the API keys of expired caches from Connect. To sign out now,
+deletes caches that have not been written for a day. VIP never reuses a cache
+older than 4 hours, and the next login deletes the API keys of expired caches
+from Connect. To sign out now,
delete the `vip/auth` folder. With no home directory and no `XDG_CACHE_HOME`,
VIP skips the cache.
diff --git a/selftests/test_auth_cache.py b/selftests/test_auth_cache.py
index ddd1f6096..f121e09ce 100644
--- a/selftests/test_auth_cache.py
+++ b/selftests/test_auth_cache.py
@@ -1225,14 +1225,17 @@ def test_prunes_expired_caches_from_other_directories(self, tmp_path, monkeypatc
monkeypatch.chdir(tmp_path)
monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
base = tmp_path / "xdg" / "vip" / "auth"
- expired = self._cache_dir(base, "0123456789abcdef", 5 * 3600)
+ expired = self._cache_dir(base, "0123456789abcdef", 25 * 3600)
fresh = self._cache_dir(base, "fedcba9876543210", 60)
- not_ours = self._cache_dir(base, "notes", 5 * 3600)
+ not_ours = self._cache_dir(base, "notes", 25 * 3600)
+ # Past the reuse TTL but maybe still read by a long run in that directory.
+ in_use = self._cache_dir(base, "00112233445566ff", 5 * 3600)
path = prepare_auth_cache()
assert not expired.exists()
assert fresh.exists()
+ assert in_use.exists()
assert not_ours.exists()
assert path.parent.parent == base
diff --git a/src/vip/auth/cache.py b/src/vip/auth/cache.py
index 0be9731d2..9319a2b9b 100644
--- a/src/vip/auth/cache.py
+++ b/src/vip/auth/cache.py
@@ -33,9 +33,13 @@
AUTH_CACHE_FILENAME = ".vip-auth-cache.json"
-# A cached session older than this is never reused, and its directory is pruned.
+# A cached session older than this is never reused.
AUTH_CACHE_TTL_SECONDS = 4 * 3600
+# Another directory's cache is pruned only after this long. A run that reused a cache
+# just inside the TTL keeps reading its storage state for as long as its tests run.
+AUTH_CACHE_PRUNE_AFTER_SECONDS = 24 * 3600
+
# Per-directory cache folders are the first 16 hex digits of a SHA-256.
_CACHE_DIR_NAME = re.compile(r"[0-9a-f]{16}")
@@ -136,10 +140,11 @@ def _make_private_dir(directory: Path) -> None:
def _prune_expired_auth_caches(base: Path, keep: Path) -> None:
- """Delete cache directories under *base* whose newest file is past the TTL, never raising.
+ """Delete cache directories under *base* not written for a day, never raising.
- An expired cache is never reused, so it only keeps cookies and an API key on disk.
- The key itself is removed by the stale-key sweep the next login runs on Connect.
+ Such a cache is past the TTL, so it is never reused and only keeps cookies and an API
+ key on disk. The key itself is removed by the stale-key sweep the next login runs on
+ Connect. The margin over the TTL keeps a long run in another directory working.
"""
now = time.time()
try:
@@ -151,7 +156,7 @@ def _prune_expired_auth_caches(base: Path, keep: Path) -> None:
continue
try:
newest = max((f.stat().st_mtime for f in directory.iterdir()), default=0.0)
- if now - newest > AUTH_CACHE_TTL_SECONDS:
+ if now - newest > AUTH_CACHE_PRUNE_AFTER_SECONDS:
shutil.rmtree(directory)
except OSError as exc:
logger.debug("Could not prune expired auth cache %s: %s", directory, exc)
diff --git a/website/src/pages/guide.astro b/website/src/pages/guide.astro
index 846c8c67c..3bcaa67dc 100644
--- a/website/src/pages/guide.astro
+++ b/website/src/pages/guide.astro
@@ -116,8 +116,9 @@ import "../styles/docs.css";
Only your user can read these folders. Each vip verify
- or vip cleanup deletes caches older than 4 hours, and
- the next login removes their API keys from Connect. To sign out
+ or vip cleanup deletes caches that have not been
+ written for a day, and the next login removes their API keys from
+ Connect. To sign out
sooner, delete the vip/auth folder. Older releases
saved .vip-auth-cache.json and
.vip-auth-cache.meta.json in the working directory;