iis-access 0.1.1__tar.gz

iis_access-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+.env
+.env.local
+*.tsbuildinfo
+coverage/
+drizzle/
+.DS_Store
+worktrees/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/

iis_access-0.1.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: iis-access
+Version: 0.1.1
+Summary: Python auth library for IIS tools ecosystem
+Project-URL: Repository, https://github.com/hschmied/account
+Project-URL: Homepage, https://iis.tools
+Author-email: IIS Labs <dev@iis.tools>
+License-Expression: MIT
+Keywords: api-key,auth,iis,provider-resolution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# iis-access
+
+Python auth library for IIS tools ecosystem. Provides optional authentication, provider resolution, managed key retrieval, and usage reporting for Python-based IIS CLI tools (aria, sonar, iris).
+
+## Installation
+
+```bash
+pip install iis-access
+```
+
+## Quick Start
+
+```python
+from iis_access import resolve_provider, report_usage
+
+# Resolve the best available provider for a task
+resolution = await resolve_provider("tts", preferred="elevenlabs")
+print(resolution.provider, resolution.method)
+
+# Report usage (fire-and-forget, never raises)
+await report_usage("aria", credits=1.5)
+```

iis_access-0.1.1/README.md

@@ -0,0 +1,22 @@
+# iis-access
+
+Python auth library for IIS tools ecosystem. Provides optional authentication, provider resolution, managed key retrieval, and usage reporting for Python-based IIS CLI tools (aria, sonar, iris).
+
+## Installation
+
+```bash
+pip install iis-access
+```
+
+## Quick Start
+
+```python
+from iis_access import resolve_provider, report_usage
+
+# Resolve the best available provider for a task
+resolution = await resolve_provider("tts", preferred="elevenlabs")
+print(resolution.provider, resolution.method)
+
+# Report usage (fire-and-forget, never raises)
+await report_usage("aria", credits=1.5)
+```

iis_access-0.1.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iis-access"
+version = "0.1.1"
+description = "Python auth library for IIS tools ecosystem"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "IIS Labs", email = "dev@iis.tools"}]
+keywords = ["iis", "auth", "api-key", "provider-resolution"]
+dependencies = [
+    "aiohttp>=3.9",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Repository = "https://github.com/hschmied/account"
+Homepage = "https://iis.tools"
+
+[project.optional-dependencies]
+keyring = ["keyring>=25.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "aioresponses>=0.7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iis_access"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

iis_access-0.1.1/src/iis_access/__init__.py

@@ -0,0 +1,19 @@
+"""IIS Tools Python access library - optional auth integration for CLI tools."""
+
+from ._types import AuthContext, ProviderResolution, NoProviderAvailable
+from .auth import get_auth_context, is_authenticated
+from .provider import resolve_provider, register_free_provider
+from .managed_keys import get_managed_key
+from .usage import report_usage
+
+__all__ = [
+    "AuthContext",
+    "ProviderResolution",
+    "NoProviderAvailable",
+    "get_auth_context",
+    "is_authenticated",
+    "resolve_provider",
+    "register_free_provider",
+    "get_managed_key",
+    "report_usage",
+]

iis_access-0.1.1/src/iis_access/_types.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class AuthContext:
+    account_id: str
+    access_token: str
+    plan: str  # "free", "pro", "enterprise"
+
+
+@dataclass
+class ProviderResolution:
+    provider: str  # "openai", "elevenlabs", "edge-tts", etc.
+    method: str  # "nexus", "managed_key", "local_key", "free"
+    api_key: str | None  # The key to use (None for free providers)
+    endpoint: str | None  # Override endpoint (for Nexus)
+    credits_estimated: float | None  # Estimated credit cost
+
+
+class NoProviderAvailable(Exception):
+    """Raised when no provider can fulfill the request."""
+
+    pass

iis_access-0.1.1/src/iis_access/auth.py

@@ -0,0 +1,150 @@
+import asyncio
+import logging
+
+from ._types import AuthContext
+from .config import get_account_url, get_credentials, is_auth_disabled
+
+logger = logging.getLogger("iis_access")
+
+_cached_context: AuthContext | None = None
+_refresh_lock: asyncio.Lock | None = None
+
+
+def _get_lock() -> asyncio.Lock:
+    global _refresh_lock
+    if _refresh_lock is None:
+        _refresh_lock = asyncio.Lock()
+    return _refresh_lock
+
+
+async def get_auth_context() -> AuthContext | None:
+    """Get authentication context. Returns None if not authenticated."""
+    global _cached_context
+
+    if is_auth_disabled():
+        return None
+
+    if _cached_context is not None:
+        return _cached_context
+
+    async with _get_lock():
+        # Double-check after acquiring lock
+        if _cached_context is not None:
+            return _cached_context
+
+        creds = get_credentials()
+        if not creds or "accountId" not in creds:
+            return None
+
+        account_id = creds["accountId"]
+        refresh_token = _get_refresh_token(account_id)
+        if not refresh_token:
+            return None
+
+        # Exchange refresh token for access token
+        try:
+            import aiohttp
+
+            account_url = get_account_url()
+            timeout = aiohttp.ClientTimeout(total=5)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                resp = await session.post(
+                    f"{account_url}/auth/refresh",
+                    json={"refreshToken": refresh_token},
+                )
+                if resp.status != 200:
+                    logger.info(
+                        "Token refresh failed (status %d), continuing without auth",
+                        resp.status,
+                    )
+                    return None
+
+                data = await resp.json()
+                access_token = data.get("accessToken")
+                new_refresh_token = data.get("refreshToken")
+                plan = data.get("plan") or _extract_plan_from_jwt(access_token)
+
+                if not access_token:
+                    return None
+
+                # Store new refresh token back
+                if new_refresh_token:
+                    _store_refresh_token(account_id, new_refresh_token)
+
+                _cached_context = AuthContext(
+                    account_id=account_id,
+                    access_token=access_token,
+                    plan=plan,
+                )
+                return _cached_context
+
+        except Exception as e:
+            logger.warning("Auth failed (non-fatal): %s", e)
+            return None
+
+
+def is_authenticated() -> bool:
+    """Synchronous check if there are credentials available."""
+    creds = get_credentials()
+    return creds is not None and "accountId" in creds
+
+
+def _get_refresh_token(account_id: str) -> str | None:
+    """Try keyring first, then fall back to credentials file."""
+    # Try keyring (optional dependency)
+    kr = _get_keyring()
+    if kr:
+        try:
+            token = kr.get_password("iis.tools", account_id)
+            if token:
+                return token
+        except Exception:
+            pass
+
+    # Fall back to credentials file
+    creds = get_credentials()
+    if creds and "refreshToken" in creds:
+        return creds["refreshToken"]
+
+    return None
+
+
+def _store_refresh_token(account_id: str, token: str) -> None:
+    """Store refresh token in keyring if available."""
+    kr = _get_keyring()
+    if kr:
+        try:
+            kr.set_password("iis.tools", account_id, token)
+        except Exception as e:
+            logger.debug("Failed to store refresh token in keyring: %s", e)
+
+
+def _extract_plan_from_jwt(token: str | None) -> str:
+    """Extract plan claim from JWT payload without verifying signature."""
+    if not token:
+        return "free"
+    try:
+        import base64, json as _json
+        payload = token.split(".")[1]
+        payload += "=" * (4 - len(payload) % 4)
+        claims = _json.loads(base64.urlsafe_b64decode(payload))
+        return claims.get("plan", "free")
+    except Exception:
+        return "free"
+
+
+def _get_keyring():
+    """Lazy import keyring (optional dependency)."""
+    try:
+        import keyring
+
+        return keyring
+    except ImportError:
+        return None
+
+
+def _reset_auth_cache() -> None:
+    """Reset auth cache (for testing)."""
+    global _cached_context, _refresh_lock
+    _cached_context = None
+    _refresh_lock = None

iis_access-0.1.1/src/iis_access/config.py

@@ -0,0 +1,45 @@
+import json
+import os
+from pathlib import Path
+
+_IIS_DIR = Path.home() / ".iis"
+
+
+def get_account_url() -> str:
+    if url := os.environ.get("IIS_ACCOUNT_URL"):
+        return url.rstrip("/")
+    config = _load_config()
+    return config.get("accountUrl", "https://account.iis.tools").rstrip("/")
+
+
+def get_nexus_url() -> str:
+    if url := os.environ.get("IIS_NEXUS_URL"):
+        return url.rstrip("/")
+    config = _load_config()
+    return config.get("nexusUrl", "http://localhost:9666").rstrip("/")
+
+
+def is_auth_disabled() -> bool:
+    return os.environ.get("IIS_NO_AUTH") == "1"
+
+
+def get_credentials() -> dict | None:
+    path = _IIS_DIR / "credentials.json"
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _load_config() -> dict:
+    path = _IIS_DIR / "config.json"
+    if not path.exists():
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}

iis_access-0.1.1/src/iis_access/managed_keys.py

@@ -0,0 +1,54 @@
+import logging
+
+from .auth import get_auth_context
+from .config import get_account_url
+
+logger = logging.getLogger("iis_access")
+
+# In-memory cache for managed keys (process lifetime)
+_key_cache: dict[str, str] = {}
+
+
+async def get_managed_key(provider: str) -> str | None:
+    """
+    Retrieve user's managed API key for a provider from iis-account.
+    Returns None if not authenticated, no key exists, or unreachable.
+    """
+    if provider in _key_cache:
+        return _key_cache[provider]
+
+    context = await get_auth_context()
+    if context is None:
+        return None
+
+    try:
+        import aiohttp
+
+        account_url = get_account_url()
+        timeout = aiohttp.ClientTimeout(total=5)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            resp = await session.get(
+                f"{account_url}/keys/managed/{provider}",
+                headers={"Authorization": f"Bearer {context.access_token}"},
+            )
+            if resp.status == 200:
+                data = await resp.json()
+                key = data.get("key")
+                if key:
+                    _key_cache[provider] = key
+                    return key
+            elif resp.status == 404:
+                logger.debug("No managed key for provider '%s'", provider)
+            else:
+                logger.debug(
+                    "Managed key retrieval failed (status %d)", resp.status
+                )
+    except Exception as e:
+        logger.debug("Managed key retrieval failed (non-fatal): %s", e)
+
+    return None
+
+
+def _reset_key_cache() -> None:
+    """Reset managed key cache (for testing)."""
+    _key_cache.clear()

iis_access-0.1.1/src/iis_access/nexus.py

@@ -0,0 +1,19 @@
+import logging
+
+from .config import get_nexus_url
+
+logger = logging.getLogger("iis_access")
+
+
+async def is_nexus_running() -> bool:
+    """Check if Nexus local agent is running and responsive."""
+    try:
+        import aiohttp
+
+        nexus_url = get_nexus_url()
+        timeout = aiohttp.ClientTimeout(total=1)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            resp = await session.get(f"{nexus_url}/health")
+            return resp.status == 200
+    except Exception:
+        return False

iis_access-0.1.1/src/iis_access/provider.py

@@ -0,0 +1,142 @@
+import os
+import logging
+import shutil
+from typing import Callable
+
+from ._types import ProviderResolution, NoProviderAvailable
+from .nexus import is_nexus_running
+from .managed_keys import get_managed_key
+from .auth import get_auth_context
+
+logger = logging.getLogger("iis_access")
+
+# Known env var names for local API keys
+_ENV_KEY_MAP: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "elevenlabs": "ELEVENLABS_API_KEY",
+    "azure-openai": "AZURE_OPENAI_API_KEY",
+    "google-ai": "GOOGLE_AI_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+}
+
+# Free provider registry
+_FREE_PROVIDERS: dict[str, list[tuple[str, Callable[[], bool] | None]]] = {
+    "tts": [
+        ("edge-tts", None),  # Always available (pip package)
+        ("mac-say", lambda: shutil.which("say") is not None),
+    ],
+    "transcription": [
+        ("whisper-local", lambda: shutil.which("whisper") is not None),
+    ],
+}
+
+
+def register_free_provider(
+    task_type: str,
+    provider: str,
+    check: Callable[[], bool] | None = None,
+) -> None:
+    """Register a free provider for a task type."""
+    if task_type not in _FREE_PROVIDERS:
+        _FREE_PROVIDERS[task_type] = []
+    _FREE_PROVIDERS[task_type].append((provider, check))
+
+
+async def resolve_provider(
+    task_type: str,
+    preferred: str | None = None,
+    require_capability: str | None = None,
+) -> ProviderResolution:
+    """
+    Resolve the best provider for the given task type.
+
+    Resolution order:
+    1. Nexus with pooled credits
+    2. Nexus with managed key
+    3. Local API key (env var)
+    4. Free provider
+    5. Raise NoProviderAvailable
+    """
+    context = await get_auth_context()
+
+    # Branch 1 & 2: Nexus
+    if await is_nexus_running():
+        nexus_url = _get_nexus_endpoint()
+
+        # Branch 1: Nexus with pooled credits (if authenticated with plan)
+        if context and context.plan in ("pro", "enterprise"):
+            return ProviderResolution(
+                provider=preferred or "nexus-default",
+                method="nexus",
+                api_key=None,
+                endpoint=nexus_url,
+                credits_estimated=None,  # Nexus handles pricing
+            )
+
+        # Branch 2: Nexus with managed key
+        if context and preferred:
+            managed_key = await get_managed_key(preferred)
+            if managed_key:
+                return ProviderResolution(
+                    provider=preferred,
+                    method="managed_key",
+                    api_key=managed_key,
+                    endpoint=nexus_url,
+                    credits_estimated=None,
+                )
+
+    # Branch 3: Local API key
+    providers_to_check = [preferred] if preferred else list(_ENV_KEY_MAP.keys())
+    for provider in providers_to_check:
+        if not provider:
+            continue
+        env_var = _ENV_KEY_MAP.get(provider)
+        if env_var:
+            key = os.environ.get(env_var)
+            if key:
+                return ProviderResolution(
+                    provider=provider,
+                    method="local_key",
+                    api_key=key,
+                    endpoint=None,
+                    credits_estimated=None,
+                )
+
+    # Also check managed key without Nexus (direct access)
+    if context and preferred:
+        managed_key = await get_managed_key(preferred)
+        if managed_key:
+            return ProviderResolution(
+                provider=preferred,
+                method="managed_key",
+                api_key=managed_key,
+                endpoint=None,
+                credits_estimated=None,
+            )
+
+    # Branch 4: Free provider
+    free_providers = _FREE_PROVIDERS.get(task_type, [])
+    for name, check_fn in free_providers:
+        if check_fn is None or check_fn():
+            return ProviderResolution(
+                provider=name,
+                method="free",
+                api_key=None,
+                endpoint=None,
+                credits_estimated=0,
+            )
+
+    # Branch 5: No provider available
+    raise NoProviderAvailable(
+        f"No provider available for task type '{task_type}'"
+        + (f" (preferred: {preferred})" if preferred else "")
+    )
+
+
+def _get_nexus_endpoint() -> str:
+    from .config import get_nexus_url
+
+    return get_nexus_url()

iis_access-0.1.1/src/iis_access/sync.py

@@ -0,0 +1,30 @@
+import asyncio
+
+from ._types import ProviderResolution
+
+
+def resolve_provider_sync(
+    task_type: str,
+    preferred: str | None = None,
+    require_capability: str | None = None,
+) -> ProviderResolution:
+    """Sync wrapper for resolve_provider."""
+    from .provider import resolve_provider
+
+    return asyncio.run(resolve_provider(task_type, preferred, require_capability))
+
+
+def get_managed_key_sync(provider: str) -> str | None:
+    """Sync wrapper for get_managed_key."""
+    from .managed_keys import get_managed_key
+
+    return asyncio.run(get_managed_key(provider))
+
+
+def report_usage_sync(
+    service: str, credits: float = 0, requests: int = 1
+) -> None:
+    """Sync wrapper for report_usage."""
+    from .usage import report_usage
+
+    asyncio.run(report_usage(service, credits, requests))

iis_access-0.1.1/src/iis_access/usage.py

@@ -0,0 +1,40 @@
+import logging
+
+from .auth import get_auth_context
+from .config import get_account_url
+
+logger = logging.getLogger("iis_access")
+
+
+async def report_usage(
+    service: str,
+    credits: float = 0,
+    requests: int = 1,
+) -> None:
+    """
+    Fire-and-forget usage report to iis-account.
+    Never raises - logs warnings on failure.
+    Skipped if not authenticated.
+    """
+    context = await get_auth_context()
+    if context is None:
+        return
+
+    try:
+        import aiohttp
+
+        account_url = get_account_url()
+        timeout = aiohttp.ClientTimeout(total=5)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            await session.post(
+                f"{account_url}/usage/record",
+                json={
+                    "accountId": context.account_id,
+                    "service": service,
+                    "requests": requests,
+                    "credits": credits,
+                },
+                headers={"Authorization": f"Bearer {context.access_token}"},
+            )
+    except Exception as e:
+        logger.debug("Usage reporting failed (non-fatal): %s", e)

iis_access-0.1.1/tests/conftest.py

@@ -0,0 +1,14 @@
+import pytest
+
+from iis_access.auth import _reset_auth_cache
+from iis_access.managed_keys import _reset_key_cache
+
+
+@pytest.fixture(autouse=True)
+def reset_caches():
+    """Reset all caches between tests."""
+    _reset_auth_cache()
+    _reset_key_cache()
+    yield
+    _reset_auth_cache()
+    _reset_key_cache()

iis_access-0.1.1/tests/test_auth.py

@@ -0,0 +1,120 @@
+import json
+from unittest.mock import patch
+
+import pytest
+from aioresponses import aioresponses
+
+from iis_access._types import AuthContext
+from iis_access.auth import get_auth_context, is_authenticated
+
+
+@pytest.fixture
+def mock_credentials(tmp_path):
+    """Create a temporary credentials file."""
+    iis_dir = tmp_path / ".iis"
+    iis_dir.mkdir()
+    creds_file = iis_dir / "credentials.json"
+
+    def _write(data: dict):
+        creds_file.write_text(json.dumps(data))
+        return iis_dir
+
+    return _write
+
+
+class TestGetAuthContext:
+    async def test_returns_none_when_no_credentials(self):
+        with patch("iis_access.auth.get_credentials", return_value=None):
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_returns_none_when_auth_disabled(self):
+        with patch.dict("os.environ", {"IIS_NO_AUTH": "1"}):
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_returns_none_when_no_account_id(self):
+        with patch(
+            "iis_access.auth.get_credentials",
+            return_value={"refreshToken": "tok"},
+        ):
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_returns_none_when_no_refresh_token(self):
+        with patch(
+            "iis_access.auth.get_credentials",
+            return_value={"accountId": "acc-123"},
+        ):
+            with patch("iis_access.auth._get_keyring", return_value=None):
+                result = await get_auth_context()
+                assert result is None
+
+    async def test_returns_auth_context_on_successful_refresh(self):
+        creds = {"accountId": "acc-123", "refreshToken": "iis_rt_test"}
+
+        with (
+            patch("iis_access.auth.get_credentials", return_value=creds),
+            patch("iis_access.auth._get_keyring", return_value=None),
+            patch(
+                "iis_access.auth.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post(
+                "http://localhost:9060/auth/refresh",
+                payload={
+                    "accessToken": "jwt-token-abc",
+                    "refreshToken": "iis_rt_new",
+                    "plan": "pro",
+                },
+            )
+
+            result = await get_auth_context()
+
+            assert result is not None
+            assert isinstance(result, AuthContext)
+            assert result.account_id == "acc-123"
+            assert result.access_token == "jwt-token-abc"
+            assert result.plan == "pro"
+
+    async def test_returns_none_on_refresh_failure(self):
+        creds = {"accountId": "acc-123", "refreshToken": "iis_rt_test"}
+
+        with (
+            patch("iis_access.auth.get_credentials", return_value=creds),
+            patch("iis_access.auth._get_keyring", return_value=None),
+            patch(
+                "iis_access.auth.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post(
+                "http://localhost:9060/auth/refresh",
+                status=401,
+            )
+
+            result = await get_auth_context()
+            assert result is None
+
+
+class TestIsAuthenticated:
+    def test_returns_false_when_no_credentials(self):
+        with patch("iis_access.auth.get_credentials", return_value=None):
+            assert is_authenticated() is False
+
+    def test_returns_false_when_no_account_id(self):
+        with patch(
+            "iis_access.auth.get_credentials",
+            return_value={"refreshToken": "tok"},
+        ):
+            assert is_authenticated() is False
+
+    def test_returns_true_when_credentials_exist(self):
+        with patch(
+            "iis_access.auth.get_credentials",
+            return_value={"accountId": "acc-123", "refreshToken": "tok"},
+        ):
+            assert is_authenticated() is True

iis_access-0.1.1/tests/test_graceful_degradation.py

@@ -0,0 +1,96 @@
+"""Test that all functions degrade gracefully when services are unavailable."""
+
+from unittest.mock import patch, AsyncMock
+
+from aioresponses import aioresponses
+
+from iis_access.auth import get_auth_context
+from iis_access.managed_keys import get_managed_key
+from iis_access.usage import report_usage
+from iis_access.nexus import is_nexus_running
+
+
+class TestGracefulDegradation:
+    async def test_auth_returns_none_without_credentials(self):
+        with patch("iis_access.auth.get_credentials", return_value=None):
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_auth_returns_none_on_network_timeout(self):
+        creds = {"accountId": "acc-123", "refreshToken": "iis_rt_test"}
+
+        with (
+            patch("iis_access.auth.get_credentials", return_value=creds),
+            patch("iis_access.auth._get_keyring", return_value=None),
+            patch(
+                "iis_access.auth.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post(
+                "http://localhost:9060/auth/refresh",
+                exception=TimeoutError("Connection timed out"),
+            )
+
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_auth_returns_none_on_server_error(self):
+        creds = {"accountId": "acc-123", "refreshToken": "iis_rt_test"}
+
+        with (
+            patch("iis_access.auth.get_credentials", return_value=creds),
+            patch("iis_access.auth._get_keyring", return_value=None),
+            patch(
+                "iis_access.auth.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post(
+                "http://localhost:9060/auth/refresh",
+                status=500,
+            )
+
+            result = await get_auth_context()
+            assert result is None
+
+    async def test_managed_key_returns_none_without_auth(self):
+        with patch(
+            "iis_access.managed_keys.get_auth_context",
+            new_callable=AsyncMock,
+            return_value=None,
+        ):
+            result = await get_managed_key("openai")
+            assert result is None
+
+    async def test_usage_silent_on_failure(self):
+        """report_usage must never raise, even on complete failure."""
+        with patch(
+            "iis_access.usage.get_auth_context",
+            new_callable=AsyncMock,
+            return_value=None,
+        ):
+            # Should complete without raising
+            await report_usage("aria", credits=1.0)
+
+    async def test_nexus_returns_false_when_not_running(self):
+        with aioresponses() as mocked:
+            mocked.get(
+                "http://localhost:9070/health",
+                exception=ConnectionError("Connection refused"),
+            )
+
+            result = await is_nexus_running()
+            assert result is False
+
+    async def test_nexus_returns_false_on_non_200(self):
+        with aioresponses() as mocked:
+            mocked.get(
+                "http://localhost:9070/health",
+                status=503,
+            )
+
+            result = await is_nexus_running()
+            assert result is False

iis_access-0.1.1/tests/test_managed_keys.py

@@ -0,0 +1,115 @@
+from unittest.mock import patch, AsyncMock
+
+import pytest
+from aioresponses import aioresponses
+
+from iis_access._types import AuthContext
+from iis_access.managed_keys import get_managed_key
+
+
+def _make_context():
+    return AuthContext(
+        account_id="acc-123",
+        access_token="jwt-token",
+        plan="pro",
+    )
+
+
+class TestGetManagedKey:
+    async def test_returns_none_when_not_authenticated(self):
+        with patch(
+            "iis_access.managed_keys.get_auth_context",
+            new_callable=AsyncMock,
+            return_value=None,
+        ):
+            result = await get_managed_key("openai")
+            assert result is None
+
+    async def test_returns_key_on_success(self):
+        with (
+            patch(
+                "iis_access.managed_keys.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=_make_context(),
+            ),
+            patch(
+                "iis_access.managed_keys.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.get(
+                "http://localhost:9060/keys/managed/openai",
+                payload={"key": "sk-managed-abc"},
+            )
+
+            result = await get_managed_key("openai")
+            assert result == "sk-managed-abc"
+
+    async def test_returns_cached_key_on_second_call(self):
+        with (
+            patch(
+                "iis_access.managed_keys.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=_make_context(),
+            ),
+            patch(
+                "iis_access.managed_keys.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.get(
+                "http://localhost:9060/keys/managed/elevenlabs",
+                payload={"key": "sk-el-abc"},
+            )
+
+            # First call hits API
+            result1 = await get_managed_key("elevenlabs")
+            assert result1 == "sk-el-abc"
+
+            # Second call uses cache (no mock needed)
+            result2 = await get_managed_key("elevenlabs")
+            assert result2 == "sk-el-abc"
+
+    async def test_returns_none_on_404(self):
+        with (
+            patch(
+                "iis_access.managed_keys.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=_make_context(),
+            ),
+            patch(
+                "iis_access.managed_keys.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.get(
+                "http://localhost:9060/keys/managed/unknown",
+                status=404,
+            )
+
+            result = await get_managed_key("unknown")
+            assert result is None
+
+    async def test_returns_none_on_network_error(self):
+        with (
+            patch(
+                "iis_access.managed_keys.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=_make_context(),
+            ),
+            patch(
+                "iis_access.managed_keys.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.get(
+                "http://localhost:9060/keys/managed/openai",
+                exception=ConnectionError("Network unreachable"),
+            )
+
+            result = await get_managed_key("openai")
+            assert result is None

iis_access-0.1.1/tests/test_provider.py

@@ -0,0 +1,142 @@
+from unittest.mock import patch, AsyncMock
+
+import pytest
+
+from iis_access._types import NoProviderAvailable, ProviderResolution
+from iis_access.provider import resolve_provider, register_free_provider
+
+
+class TestResolveProvider:
+    async def test_returns_local_key_when_env_var_set(self):
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=False,
+            ),
+            patch.dict("os.environ", {"OPENAI_API_KEY": "sk-test-123"}),
+        ):
+            result = await resolve_provider("llm", preferred="openai")
+
+            assert isinstance(result, ProviderResolution)
+            assert result.provider == "openai"
+            assert result.method == "local_key"
+            assert result.api_key == "sk-test-123"
+            assert result.endpoint is None
+
+    async def test_returns_free_provider_when_no_keys(self):
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=False,
+            ),
+            patch.dict("os.environ", {}, clear=True),
+        ):
+            result = await resolve_provider("tts")
+
+            assert result.provider == "edge-tts"
+            assert result.method == "free"
+            assert result.api_key is None
+            assert result.credits_estimated == 0
+
+    async def test_raises_no_provider_when_no_options(self):
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=False,
+            ),
+            patch.dict("os.environ", {}, clear=True),
+        ):
+            with pytest.raises(NoProviderAvailable, match="unknown-task"):
+                await resolve_provider("unknown-task", preferred="nonexistent")
+
+    async def test_prefers_nexus_for_pro_plan(self):
+        from iis_access._types import AuthContext
+
+        ctx = AuthContext(account_id="acc-1", access_token="jwt", plan="pro")
+
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=ctx,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=True,
+            ),
+            patch(
+                "iis_access.provider._get_nexus_endpoint",
+                return_value="http://localhost:9070",
+            ),
+        ):
+            result = await resolve_provider("llm", preferred="openai")
+
+            assert result.method == "nexus"
+            assert result.endpoint == "http://localhost:9070"
+
+    async def test_local_key_scan_without_preferred(self):
+        """When no preferred provider, scans all known env vars."""
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=False,
+            ),
+            patch.dict(
+                "os.environ",
+                {"ANTHROPIC_API_KEY": "sk-ant-test"},
+                clear=True,
+            ),
+        ):
+            result = await resolve_provider("llm")
+
+            assert result.provider == "anthropic"
+            assert result.method == "local_key"
+            assert result.api_key == "sk-ant-test"
+
+
+class TestRegisterFreeProvider:
+    async def test_register_and_use_free_provider(self):
+        register_free_provider("image-gen", "local-sd", check=lambda: True)
+
+        with (
+            patch(
+                "iis_access.provider.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=None,
+            ),
+            patch(
+                "iis_access.provider.is_nexus_running",
+                new_callable=AsyncMock,
+                return_value=False,
+            ),
+            patch.dict("os.environ", {}, clear=True),
+        ):
+            result = await resolve_provider("image-gen")
+
+            assert result.provider == "local-sd"
+            assert result.method == "free"

iis_access-0.1.1/tests/test_usage.py

@@ -0,0 +1,73 @@
+from unittest.mock import patch, AsyncMock
+
+from aioresponses import aioresponses
+
+from iis_access._types import AuthContext
+from iis_access.usage import report_usage
+
+
+class TestReportUsage:
+    async def test_does_nothing_when_not_authenticated(self):
+        with patch(
+            "iis_access.usage.get_auth_context",
+            new_callable=AsyncMock,
+            return_value=None,
+        ):
+            # Should not raise
+            await report_usage("aria", credits=1.0)
+
+    async def test_sends_post_when_authenticated(self):
+        ctx = AuthContext(
+            account_id="acc-123",
+            access_token="jwt-token",
+            plan="pro",
+        )
+
+        with (
+            patch(
+                "iis_access.usage.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=ctx,
+            ),
+            patch(
+                "iis_access.usage.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post("http://localhost:9060/usage/record", status=200)
+
+            await report_usage("aria", credits=2.5, requests=1)
+
+            # Verify the request was made
+            requests_made = mocked.requests
+            key = ("POST", mocked.requests)
+            # aioresponses stores requests - verify at least one was made
+            assert len(requests_made) > 0
+
+    async def test_handles_network_error_gracefully(self):
+        ctx = AuthContext(
+            account_id="acc-123",
+            access_token="jwt-token",
+            plan="pro",
+        )
+
+        with (
+            patch(
+                "iis_access.usage.get_auth_context",
+                new_callable=AsyncMock,
+                return_value=ctx,
+            ),
+            patch(
+                "iis_access.usage.get_account_url",
+                return_value="http://localhost:9060",
+            ),
+            aioresponses() as mocked,
+        ):
+            mocked.post(
+                "http://localhost:9060/usage/record",
+                exception=ConnectionError("Network down"),
+            )
+
+            # Should not raise
+            await report_usage("aria", credits=1.0)