tokentoss 0.1.0__py3-none-any.whl

tokentoss/client.py

@@ -0,0 +1,250 @@
+"""IAP-authenticated HTTP client.
+
+Provides IAPClient which automatically handles Google ID token
+injection for requests to IAP-protected services.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+import requests
+from google.auth.transport.requests import Request
+
+from .exceptions import NoCredentialsError
+from .storage import FileStorage
+
+if TYPE_CHECKING:
+    from .auth_manager import AuthManager
+
+
+class IAPClient:
+    """HTTP client that adds IAP authentication tokens automatically.
+
+    Discovers credentials via a fallback chain:
+    1. Explicit AuthManager (passed to constructor)
+    2. Module-level tokentoss.CREDENTIALS (set by AuthManager on login)
+    3. Token file (TOKENTOSS_TOKEN_FILE env var or default platformdirs path)
+
+    Automatically retries once on 401 by refreshing the token.
+
+    Usage:
+        client = IAPClient(base_url="https://my-iap-service.run.app")
+        data = client.get_json("/api/data")
+
+    Or as a context manager:
+        with IAPClient(base_url="https://my-service.run.app") as client:
+            data = client.get_json("/api/data")
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        auth_manager: AuthManager | None = None,
+        timeout: int = 30,
+    ) -> None:
+        """Initialize IAPClient.
+
+        Args:
+            base_url: Optional base URL for relative paths (e.g. "https://my-service.run.app").
+            auth_manager: Optional AuthManager for credential discovery.
+                If not provided, falls back to module-level CREDENTIALS or token file.
+            timeout: Request timeout in seconds. Default 30.
+        """
+        self.base_url = base_url.rstrip("/") if base_url else None
+        self.timeout = timeout
+        self._auth_manager = auth_manager
+        self._session = requests.Session()
+        self._fallback_storage: FileStorage | None = None
+
+    def _get_fallback_storage(self) -> FileStorage:
+        """Get or create cached FileStorage for token discovery."""
+        if self._fallback_storage is None:
+            token_path = os.environ.get("TOKENTOSS_TOKEN_FILE")
+            self._fallback_storage = FileStorage(path=token_path)
+        return self._fallback_storage
+
+    def _get_id_token(self, force_refresh: bool = False) -> str:
+        """Find and return a valid ID token.
+
+        Discovery chain:
+        1. Explicit auth_manager passed in constructor
+        2. Module-level tokentoss.CREDENTIALS variable
+        3. Token file (TOKENTOSS_TOKEN_FILE env var or default location)
+
+        Args:
+            force_refresh: Force a token refresh before returning.
+
+        Returns:
+            A valid ID token string.
+
+        Raises:
+            NoCredentialsError: If no valid credentials found anywhere.
+        """
+        # 1. Explicit AuthManager
+        token = self._try_auth_manager(force_refresh)
+        if token:
+            return token
+
+        # 2. Module-level credentials
+        token = self._try_module_credentials(force_refresh)
+        if token:
+            return token
+
+        # 3. Token file (env var or default path)
+        token = self._try_storage()
+        if token:
+            return token
+
+        raise NoCredentialsError(
+            "No valid credentials found. Use GoogleAuthWidget to authenticate."
+        )
+
+    def _try_auth_manager(self, force_refresh: bool) -> str | None:
+        """Try to get ID token from explicit AuthManager."""
+        if self._auth_manager is None:
+            return None
+
+        if force_refresh:
+            self._auth_manager.refresh_tokens()
+
+        return self._auth_manager.id_token
+
+    def _try_module_credentials(self, force_refresh: bool) -> str | None:
+        """Try to get ID token from module-level CREDENTIALS."""
+        import tokentoss
+
+        creds = tokentoss.CREDENTIALS
+        if creds is None:
+            return None
+
+        if force_refresh or (hasattr(creds, "expired") and creds.expired):
+            creds.refresh(Request())
+
+        return getattr(creds, "id_token", None)
+
+    def _try_storage(self) -> str | None:
+        """Try to get a non-expired ID token from file storage.
+
+        Note: Storage alone cannot refresh tokens (no client config available).
+        If the stored token is expired, returns None to let the caller raise.
+        """
+        storage = self._get_fallback_storage()
+        try:
+            token_data = storage.load()
+        except Exception:
+            return None
+
+        if token_data is None:
+            return None
+
+        if token_data.is_expired:
+            return None
+
+        return token_data.id_token or None
+
+    def _build_url(self, path: str) -> str:
+        """Construct full URL from base_url and path.
+
+        Args:
+            path: Absolute URL or relative path.
+
+        Returns:
+            Full URL string.
+
+        Raises:
+            ValueError: If path is relative and no base_url is set.
+        """
+        if path.startswith(("http://", "https://")):
+            return path
+
+        if self.base_url is None:
+            raise ValueError(
+                f"Relative path {path!r} requires a base_url. "
+                "Pass base_url to IAPClient() or use an absolute URL."
+            )
+
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
+        """Make an authenticated request with auto-retry on 401.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: URL path or absolute URL.
+            **kwargs: Passed to requests.Session.request().
+
+        Returns:
+            requests.Response object.
+        """
+        url = self._build_url(path)
+
+        # Set timeout if not explicitly provided
+        kwargs.setdefault("timeout", self.timeout)
+
+        # Get token and make request
+        id_token = self._get_id_token()
+        headers = kwargs.pop("headers", None) or {}
+        headers["Authorization"] = f"Bearer {id_token}"
+        kwargs["headers"] = headers
+
+        response = self._session.request(method, url, **kwargs)
+
+        # Retry once on 401 with forced refresh
+        if response.status_code == 401:
+            try:
+                refreshed_token = self._get_id_token(force_refresh=True)
+                headers["Authorization"] = f"Bearer {refreshed_token}"
+                kwargs["headers"] = headers
+                response = self._session.request(method, url, **kwargs)
+            except (NoCredentialsError, Exception):
+                pass  # Return original 401 response
+
+        return response
+
+    # -- Public HTTP methods --
+
+    def get(self, path: str, **kwargs: Any) -> requests.Response:
+        """GET request with IAP authentication."""
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> requests.Response:
+        """POST request with IAP authentication."""
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> requests.Response:
+        """PUT request with IAP authentication."""
+        return self._request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> requests.Response:
+        """DELETE request with IAP authentication."""
+        return self._request("DELETE", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> requests.Response:
+        """PATCH request with IAP authentication."""
+        return self._request("PATCH", path, **kwargs)
+
+    def get_json(self, path: str, **kwargs: Any) -> Any:
+        """GET request, return parsed JSON. Raises on non-2xx status."""
+        response = self.get(path, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+    def post_json(self, path: str, json: Any = None, **kwargs: Any) -> Any:
+        """POST with JSON body, return parsed JSON. Raises on non-2xx status."""
+        response = self.post(path, json=json, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+    # -- Lifecycle --
+
+    def close(self) -> None:
+        """Close the underlying requests session."""
+        self._session.close()
+
+    def __enter__(self) -> IAPClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

tokentoss/configure_widget.py

@@ -0,0 +1,253 @@
+"""Configuration widget for setting up OAuth client credentials in Jupyter notebooks.
+
+Provides a password-safe input widget so credentials are entered at runtime
+and never appear in .ipynb source or version control.
+
+Usage:
+    from tokentoss import ConfigureWidget
+    display(ConfigureWidget())
+"""
+
+from __future__ import annotations
+
+import anywidget
+import traitlets
+
+from .setup import configure
+
+_ESM = """
+function render({ model, el }) {
+    const container = document.createElement('div');
+    container.className = 'tokentoss-configure';
+
+    // Client ID field
+    const idLabel = document.createElement('label');
+    idLabel.className = 'tokentoss-configure-label';
+    idLabel.textContent = 'Client ID';
+    const idInput = document.createElement('input');
+    idInput.type = 'text';
+    idInput.className = 'tokentoss-configure-input';
+    idInput.placeholder = '123456789.apps.googleusercontent.com';
+
+    // Client Secret field
+    const secretLabel = document.createElement('label');
+    secretLabel.className = 'tokentoss-configure-label';
+    secretLabel.textContent = 'Client Secret';
+    const secretInput = document.createElement('input');
+    secretInput.type = 'password';
+    secretInput.className = 'tokentoss-configure-input';
+    secretInput.placeholder = 'GOCSPX-...';
+
+    // Advanced (optional) section
+    const advancedHeader = document.createElement('div');
+    advancedHeader.className = 'tokentoss-configure-advanced-header';
+    advancedHeader.innerHTML = '▶ Advanced (optional)';
+    let advancedOpen = false;
+
+    const advancedContent = document.createElement('div');
+    advancedContent.className = 'tokentoss-configure-advanced-content';
+    advancedContent.style.display = 'none';
+
+    const projectLabel = document.createElement('label');
+    projectLabel.className = 'tokentoss-configure-label';
+    projectLabel.textContent = 'Project ID';
+    const projectInput = document.createElement('input');
+    projectInput.type = 'text';
+    projectInput.className = 'tokentoss-configure-input';
+    projectInput.placeholder = 'my-gcp-project';
+
+    advancedContent.appendChild(projectLabel);
+    advancedContent.appendChild(projectInput);
+
+    advancedHeader.addEventListener('click', () => {
+        advancedOpen = !advancedOpen;
+        advancedContent.style.display = advancedOpen ? 'block' : 'none';
+        advancedHeader.innerHTML = (advancedOpen ? '▼' : '▶') + ' Advanced (optional)';
+    });
+
+    // Submit button
+    const button = document.createElement('button');
+    button.className = 'tokentoss-configure-button';
+    button.textContent = 'Configure';
+
+    // Status display
+    const statusEl = document.createElement('div');
+    statusEl.className = 'tokentoss-configure-status';
+
+    // Assemble DOM
+    container.appendChild(idLabel);
+    container.appendChild(idInput);
+    container.appendChild(secretLabel);
+    container.appendChild(secretInput);
+    container.appendChild(advancedHeader);
+    container.appendChild(advancedContent);
+    container.appendChild(button);
+    container.appendChild(statusEl);
+    el.appendChild(container);
+
+    function updateStatus() {
+        const status = model.get('status');
+        const configured = model.get('configured');
+        statusEl.textContent = status;
+        statusEl.className = 'tokentoss-configure-status' +
+            (configured ? ' tokentoss-configure-success' : '');
+        if (status.startsWith('Error')) {
+            statusEl.className = 'tokentoss-configure-status tokentoss-configure-error';
+        }
+    }
+
+    button.addEventListener('click', () => {
+        model.set('client_id', idInput.value);
+        model.set('client_secret', secretInput.value);
+        model.set('project_id', projectInput.value);
+        model.set('_submit', model.get('_submit') + 1);
+        model.save_changes();
+    });
+
+    model.on('change:status', updateStatus);
+    model.on('change:configured', updateStatus);
+
+    updateStatus();
+}
+
+export default { render };
+"""
+
+_CSS = """
+.tokentoss-configure {
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    padding: 16px;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    background: #ffffff;
+    max-width: 400px;
+}
+
+.tokentoss-configure-label {
+    display: block;
+    font-size: 13px;
+    font-weight: 500;
+    color: #374151;
+    margin-bottom: 4px;
+    margin-top: 12px;
+}
+
+.tokentoss-configure-label:first-child {
+    margin-top: 0;
+}
+
+.tokentoss-configure-input {
+    width: 100%;
+    padding: 8px 12px;
+    font-size: 13px;
+    border: 1px solid #d1d5db;
+    border-radius: 4px;
+    box-sizing: border-box;
+}
+
+.tokentoss-configure-input:focus {
+    outline: none;
+    border-color: #4285f4;
+    box-shadow: 0 0 0 2px rgba(66, 133, 244, 0.2);
+}
+
+.tokentoss-configure-button {
+    margin-top: 16px;
+    padding: 10px 20px;
+    font-size: 14px;
+    font-weight: 500;
+    color: #ffffff;
+    background: #4285f4;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    transition: background 0.2s;
+}
+
+.tokentoss-configure-button:hover {
+    background: #3574e2;
+}
+
+.tokentoss-configure-status {
+    margin-top: 12px;
+    font-size: 13px;
+    color: #6b7280;
+}
+
+.tokentoss-configure-success {
+    color: #059669;
+}
+
+.tokentoss-configure-error {
+    color: #dc2626;
+}
+
+.tokentoss-configure-advanced-header {
+    margin-top: 16px;
+    font-size: 13px;
+    color: #6b7280;
+    cursor: pointer;
+    user-select: none;
+}
+
+.tokentoss-configure-advanced-header:hover {
+    color: #374151;
+}
+
+.tokentoss-configure-advanced-content {
+    margin-top: 4px;
+}
+"""
+
+
+class ConfigureWidget(anywidget.AnyWidget):
+    """Widget for configuring OAuth client credentials in Jupyter notebooks.
+
+    Provides password-style input fields for client_id and client_secret,
+    so credentials are entered at runtime and never appear in notebook source.
+
+    Example:
+        from tokentoss import ConfigureWidget
+        display(ConfigureWidget())
+        # Enter credentials and click Configure
+    """
+
+    client_id = traitlets.Unicode("").tag(sync=True)
+    client_secret = traitlets.Unicode("").tag(sync=True)
+    project_id = traitlets.Unicode("").tag(sync=True)
+    status = traitlets.Unicode("Enter credentials").tag(sync=True)
+    configured = traitlets.Bool(False).tag(sync=True)
+    _submit = traitlets.Int(0).tag(sync=True)
+
+    _esm = _ESM
+    _css = _CSS
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.observe(self._on_submit, names=["_submit"])
+
+    def _on_submit(self, change):
+        """Handle submit button press."""
+        if change["new"] == 0:
+            return
+
+        client_id = self.client_id.strip()
+        client_secret = self.client_secret.strip()
+
+        if not client_id or not client_secret:
+            self.status = "Error: both Client ID and Client Secret are required"
+            self.configured = False
+            return
+
+        try:
+            project_id = self.project_id.strip() or None
+            path = configure(
+                client_id=client_id,
+                client_secret=client_secret,
+                project_id=project_id,
+            )
+            self.status = f"Configured! Saved to {path}"
+            self.configured = True
+        except Exception as e:
+            self.status = f"Error: {e}"
+            self.configured = False

tokentoss/exceptions.py

@@ -0,0 +1,56 @@
+"""Custom exceptions for tokentoss."""
+
+
+class TokenTossError(Exception):
+    """Base exception for tokentoss."""
+
+    pass
+
+
+class NoCredentialsError(TokenTossError):
+    """Raised when no valid credentials are found.
+
+    This typically means:
+    - No AuthManager was passed to IAPClient
+    - tokentoss.CREDENTIALS module variable is not set
+    - No token file exists at the default location
+    - TOKENTOSS_TOKEN_FILE environment variable is not set or file doesn't exist
+
+    To authenticate, use the GoogleAuthWidget:
+        from tokentoss import GoogleAuthWidget
+        widget = GoogleAuthWidget(client_secrets_path="./client_secrets.json")
+        display(widget)
+        # Click "Sign in with Google" and complete the flow
+    """
+
+    def __init__(self, message: str | None = None):
+        if message is None:
+            message = (
+                "No valid credentials found. "
+                "Use GoogleAuthWidget to authenticate or provide credentials explicitly."
+            )
+        super().__init__(message)
+
+
+class TokenRefreshError(TokenTossError):
+    """Raised when token refresh fails."""
+
+    pass
+
+
+class TokenExchangeError(TokenTossError):
+    """Raised when authorization code exchange fails."""
+
+    pass
+
+
+class StorageError(TokenTossError):
+    """Raised when token storage operations fail."""
+
+    pass
+
+
+class InsecureFilePermissionsWarning(UserWarning):
+    """Warning issued when token file has insecure permissions."""
+
+    pass