ado-keyring 0.1.0__tar.gz

ado_keyring-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run --python ${{ matrix.python-version }} pytest tests/ -v

ado_keyring-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ado_keyring-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+/target
+__pycache__
+*.egg-info
+*.so
+*.whl
+.venv
+dist/

ado_keyring-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Taggart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ado_keyring-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: ado-keyring
+Version: 0.1.0
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: keyring>=23.0
+Requires-Dist: requests>=2.28

ado_keyring-0.1.0/README.md

@@ -0,0 +1,50 @@
+# ado-keyring
+
+A [keyring](https://pypi.org/project/keyring/) backend in pure python that authenticates to Azure DevOps package feeds using browser-based OAuth2 with PKCE.
+
+Once installed, keyring automatically discovers `ado-keyring` as a backend. Any tool that uses keyring, such as [`uv`](https://docs.astral.sh/uv/) for [alternative indexes](https://docs.astral.sh/uv/guides/integration/alternative-indexes/), will trigger browser auth when accessing Azure DevOps feeds.
+
+## Install from PyPi
+
+```sh
+uv tool install keyring --with ado-keyring
+```
+
+## Features
+
+- **Browser-based OAuth2 + PKCE** — secure, no secrets stored in config files
+- **Persistent token cache** — avoids repeated browser prompts (`~/.ado-keyring/`)
+- **Automatic token refresh** — uses refresh tokens to silently renew access
+- **Per-org session tokens** — supports multiple Azure DevOps organizations
+- **WSL-aware** — opens the Windows browser from WSL via `cmd.exe`
+- **No .NET dependency** — pure Python, unlike [`artifacts-keyring`](https://github.com/microsoft/artifacts-keyring)
+
+## Install from source
+
+```sh
+just install
+```
+
+## Install on WSL from source
+
+```sh
+tdnf install -y python3 python3-pip
+python3 -m pip install
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+uv tool install rust-just
+just install
+```
+
+## How It Works
+
+1. Binds a localhost callback server on a random port
+2. Opens the browser to Azure AD's OAuth2 authorize endpoint (PKCE, `select_account` prompt)
+3. Receives the authorization code via redirect
+4. Exchanges the code for access + refresh tokens
+5. Exchanges the access token for a `VssSessionToken` scoped to `vso.packaging`
+6. Caches all tokens to `~/.ado-keyring/token-cache.json` (file: `0600`, dir: `0700`)
+7. On subsequent calls, uses cached session tokens or silently refreshes via the refresh token
+
+## License
+
+[MIT](LICENSE)

ado_keyring-0.1.0/justfile

@@ -0,0 +1,28 @@
+set windows-shell := ["cmd.exe", "/c"]
+
+# Show the current version
+version:
+    uvx --with hatch-vcs hatchling version
+
+# Build the wheel
+build:
+    uv build
+
+# Install into the system keyring tool environment
+install: build
+    uv tool install --force keyring --with dist/ado_keyring-*.whl
+
+# Verify the backend is registered
+check:
+    keyring --list-backends
+
+# Build, install, and verify
+all: install check
+
+# Run tests
+test:
+    uv run pytest tests/ -v
+
+# Clean build artifacts
+clean:
+    rm -rf dist/ build/ *.egg-info

ado_keyring-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ado-keyring"
+dynamic = ["version"]
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["keyring>=23.0", "requests>=2.28"]
+
+[project.entry-points."keyring.backends"]
+ado-keyring = "ado_keyring:AdoKeyring"
+
+[dependency-groups]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/ado_keyring"]

ado_keyring-0.1.0/python/ado_keyring/__init__.py

@@ -0,0 +1,360 @@
+"""Keyring backend for Azure DevOps feeds using browser-based OAuth2."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import platform
+import secrets
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import keyring.backend
+import keyring.credentials
+import requests
+
+# Azure CLI public client
+_CLIENT_ID = "04b07795-8ddb-461a-bbee-02f9e1bf7b46"
+# Azure DevOps resource ID in Microsoft Entra ID, requesting default permissions and a refresh token
+_SCOPE = "499b84ac-1321-427f-aa17-267ca6975798/.default offline_access"
+_AUTH_URL = "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize"
+_TOKEN_URL = "https://login.microsoftonline.com/organizations/oauth2/v2.0/token"
+
+_LOG_PREFIX = "[ado-keyring]"
+_HTTP_TIMEOUT = 30  # seconds for all HTTP requests
+_CALLBACK_TIMEOUT = 120  # seconds to wait for browser callback
+
+
+# ── Token cache ──────────────────────────────────────────────────────────────
+
+def _cache_path() -> Path:
+    return Path.home() / ".ado-keyring" / "token-cache.json"
+
+
+def _load_cache() -> Optional[Dict[str, Any]]:
+    try:
+        return json.loads(_cache_path().read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _save_cache(cache: Dict[str, Any]) -> None:
+    path = _cache_path()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(cache, f, indent=2)
+
+
+# ── URL helpers ──────────────────────────────────────────────────────────────
+
+_DEVOPS_HOSTS = (
+    "visualstudio.com",
+    "dev.azure.com",
+    "pkgs.codedev.ms",
+    "pkgs.vsts.me",
+)
+
+
+def _is_devops_url(url: str) -> bool:
+    return any(h in url for h in _DEVOPS_HOSTS)
+
+
+def _extract_org(service_url: str) -> Optional[str]:
+    parsed = urlparse(service_url)
+    host = parsed.hostname or ""
+    if host.endswith("visualstudio.com") or host.endswith("vsts.me") or host.endswith("codedev.ms"):
+        return host.split(".")[0]
+    elif "dev.azure.com" in host:
+        parts = parsed.path.strip("/").split("/")
+        return parts[0] if parts and parts[0] else None
+    return None
+
+
+# ── PKCE ─────────────────────────────────────────────────────────────────────
+
+def _generate_pkce() -> Tuple[str, str]:
+    verifier_bytes = secrets.token_bytes(32)
+    verifier = base64.urlsafe_b64encode(verifier_bytes).rstrip(b"=").decode()
+    challenge_hash = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(challenge_hash).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+# ── WSL-aware browser opening ────────────────────────────────────────────────
+
+def _is_wsl() -> bool:
+    try:
+        return "microsoft" in Path("/proc/version").read_text().lower()
+    except OSError:
+        return False
+
+
+def _open_browser(url: str) -> None:
+    devnull = subprocess.DEVNULL
+    attempts: list[Tuple[str, list[str]]] = []
+
+    if _is_wsl():
+        attempts = [
+            (
+                "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe",
+                ["-NoProfile", "-Command", f"Start-Process '{url}'"],
+            ),
+            (
+                "/mnt/c/Windows/system32/cmd.exe",
+                ["/c", "start", "", url],
+            ),
+        ]
+    elif platform.system() == "Darwin":
+        attempts = [("open", [url])]
+    else:
+        attempts = [("xdg-open", [url])]
+
+    for cmd, args in attempts:
+        try:
+            result = subprocess.run(
+                [cmd, *args], stdin=devnull, stdout=devnull, stderr=devnull
+            )
+            if result.returncode == 0:
+                return
+        except FileNotFoundError:
+            continue
+
+    raise RuntimeError(
+        f"Could not open browser.\nPlease open this URL manually:\n{url}"
+    )
+
+
+# ── OAuth2 browser auth flow ────────────────────────────────────────────────
+
+_SUCCESS_HTML = (
+    "<html><head><title>Authentication Successful</title></head>"
+    '<body style="font-family:sans-serif;text-align:center;margin-top:80px">'
+    "<h1>Authentication Successful</h1>"
+    "<p>You can close this tab and return to the terminal.</p>"
+    "</body></html>"
+)
+
+_ERROR_HTML = (
+    "<html><head><title>Authentication Failed</title></head>"
+    '<body style="font-family:sans-serif;text-align:center;margin-top:80px">'
+    "<h1>Authentication Failed</h1>"
+    "<p>An error occurred. You can close this tab.</p>"
+    "</body></html>"
+)
+
+
+def _send_html(conn: socket.socket, html: str) -> None:
+    response = (
+        f"HTTP/1.1 200 OK\r\n"
+        f"Content-Type: text/html\r\n"
+        f"Content-Length: {len(html)}\r\n"
+        f"Connection: close\r\n\r\n"
+        f"{html}"
+    )
+    conn.sendall(response.encode())
+    conn.close()
+
+
+def _browser_auth() -> Dict[str, Any]:
+    verifier, challenge = _generate_pkce()
+    state = secrets.token_urlsafe(16)
+
+    # Bind to a random port for the OAuth callback
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("127.0.0.1", 0))
+    sock.listen(1)
+    port = sock.getsockname()[1]
+    redirect_uri = f"http://localhost:{port}"
+
+    params = urlencode({
+        "client_id": _CLIENT_ID,
+        "response_type": "code",
+        "redirect_uri": redirect_uri,
+        "scope": _SCOPE,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+        "prompt": "select_account",
+    })
+    auth_url = f"{_AUTH_URL}?{params}"
+
+    print(f"{_LOG_PREFIX} Opening browser for Azure DevOps authentication...", file=sys.stderr)
+    _open_browser(auth_url)
+
+    # Wait for the OAuth callback
+    sock.settimeout(_CALLBACK_TIMEOUT)
+    try:
+        conn, _ = sock.accept()
+    except socket.timeout:
+        sock.close()
+        raise RuntimeError(f"Timed out waiting for browser callback after {_CALLBACK_TIMEOUT}s")
+    sock.close()
+    data = conn.recv(8192).decode("utf-8", errors="replace")
+
+    # Parse GET /?code=...&state=...
+    request_line = data.split("\r\n")[0]
+    path = request_line.split(" ")[1] if " " in request_line else ""
+    parsed = urlparse(f"http://localhost{path}")
+    params_dict = parse_qs(parsed.query)
+
+    if "error" in params_dict:
+        _send_html(conn, _ERROR_HTML)
+        error = params_dict["error"][0]
+        desc = params_dict.get("error_description", [""])[0]
+        raise RuntimeError(f"{error}: {desc}")
+
+    code = params_dict.get("code", [None])[0]
+    if not code:
+        _send_html(conn, _ERROR_HTML)
+        raise RuntimeError("Missing 'code' in OAuth callback")
+
+    returned_state = params_dict.get("state", [None])[0]
+    if returned_state != state:
+        _send_html(conn, _ERROR_HTML)
+        raise RuntimeError("OAuth state mismatch — possible CSRF")
+
+    _send_html(conn, _SUCCESS_HTML)
+
+    return _exchange_code(code, redirect_uri, verifier)
+
+
+def _exchange_code(code: str, redirect_uri: str, verifier: str) -> Dict[str, Any]:
+    resp = requests.post(_TOKEN_URL, data={
+        "client_id": _CLIENT_ID,
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "code_verifier": verifier,
+    }, timeout=_HTTP_TIMEOUT)
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ── Token refresh ────────────────────────────────────────────────────────────
+
+def _refresh_access_token(refresh_token: str) -> Dict[str, Any]:
+    resp = requests.post(_TOKEN_URL, data={
+        "client_id": _CLIENT_ID,
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "scope": _SCOPE,
+    }, timeout=_HTTP_TIMEOUT)
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ── VssSessionToken exchange ─────────────────────────────────────────────────
+
+def _get_session_token(access_token: str, org: str) -> str:
+    url = f"https://vssps.dev.azure.com/{org}/_apis/token/sessiontokens?api-version=5.0-preview.1"
+    resp = requests.post(
+        url,
+        headers={"Authorization": f"Bearer {access_token}"},
+        json={"scope": "vso.packaging", "targetAccounts": []},
+        timeout=_HTTP_TIMEOUT,
+    )
+    resp.raise_for_status()
+    return resp.json()["token"]
+
+
+# ── Main authenticate logic ─────────────────────────────────────────────────
+
+def _authenticate(service_url: str) -> Optional[Tuple[str, str]]:
+    if not _is_devops_url(service_url):
+        return None
+
+    org = _extract_org(service_url)
+    if not org:
+        raise RuntimeError(
+            f"Could not extract Azure DevOps org from URL: {service_url}"
+        )
+
+    now = int(time.time())
+    cache = _load_cache()
+
+    # 1. Check cached session token (5-min buffer)
+    if cache:
+        st = cache.get("session_tokens", {}).get(org)
+        if st and st["expires_at"] > now + 300:
+            print(f"{_LOG_PREFIX} Using cached session token for '{org}'", file=sys.stderr)
+            return ("VssSessionToken", st["token"])
+
+    # 2. Get a valid access token (refresh or browser)
+    token_resp = None
+    if cache and cache.get("expires_at", 0) > now + 60:
+        pass  # access token still valid
+    elif cache and cache.get("refresh_token"):
+        print(f"{_LOG_PREFIX} Refreshing access token...", file=sys.stderr)
+        try:
+            token_resp = _refresh_access_token(cache["refresh_token"])
+        except Exception as e:
+            print(f"{_LOG_PREFIX} Refresh failed ({e}), falling back to browser", file=sys.stderr)
+            token_resp = _browser_auth()
+    else:
+        print(f"{_LOG_PREFIX} No cached token, starting browser auth...", file=sys.stderr)
+        token_resp = _browser_auth()
+
+    # Update cache with fresh access token
+    if token_resp:
+        prev_sessions = cache.get("session_tokens", {}) if cache else {}
+        cache = {
+            "access_token": token_resp["access_token"],
+            "refresh_token": token_resp.get("refresh_token"),
+            "expires_at": now + token_resp.get("expires_in", 3600),
+            "session_tokens": prev_sessions,
+        }
+
+    assert cache is not None
+
+    # 3. Exchange for VssSessionToken
+    print(f"{_LOG_PREFIX} Exchanging for VssSessionToken ({org})...", file=sys.stderr)
+    session_token = _get_session_token(cache["access_token"], org)
+
+    cache.setdefault("session_tokens", {})[org] = {
+        "token": session_token,
+        "expires_at": now + 3000,
+    }
+    _save_cache(cache)
+
+    print(f"{_LOG_PREFIX} ✓ Authenticated to '{org}'", file=sys.stderr)
+    return ("VssSessionToken", session_token)
+
+
+# ── Keyring backend ─────────────────────────────────────────────────────────
+
+class AdoKeyring(keyring.backend.KeyringBackend):
+    """Authenticates to Azure DevOps package feeds via browser OAuth2 + PKCE.
+
+    Works on WSL, Linux, and macOS. Tokens are cached to avoid repeated prompts.
+    """
+
+    priority = 10  # Higher than artifacts-keyring (9.9)
+
+    def get_password(self, service: str, username: str) -> Optional[str]:
+        result = _authenticate(service)
+        return result[1] if result else None
+
+    def get_credential(self, service: str, username: str) -> Optional[keyring.credentials.SimpleCredential]:
+        result = _authenticate(service)
+        if result:
+            return keyring.credentials.SimpleCredential(result[0], result[1])
+        return None
+
+    def set_password(self, service: str, username: str, password: str) -> None:
+        raise NotImplementedError("ado-keyring is read-only")
+
+    def delete_password(self, service: str, username: str) -> None:
+        path = _cache_path()
+        if path.exists():
+            path.unlink()
+            print(f"{_LOG_PREFIX} Token cache cleared", file=sys.stderr)
+