feat: config-driven opt-in auth via ~/.specify/auth.json

Security-first redesign: no credentials are sent unless the user
explicitly creates ~/.specify/auth.json mapping hosts to providers.

- Add authentication/config.py: loads and validates auth.json with
  host-to-provider mappings, supports token/token_env/azure-ad/azure-cli
- Refactor AuthProvider ABC: auth_headers(token, scheme) + resolve_token(entry)
- Refactor GitHubAuth: bearer scheme only, token from config entry
- Refactor AzureDevOpsAuth: 4 schemes (basic-pat, bearer, azure-cli, azure-ad)
  with dynamic token acquisition for azure-cli and azure-ad
- Rewrite authentication/http.py: host matching, redirect stripping,
  provider fallthrough on 401/403, unauthenticated fallback
- Add docs/reference/authentication.md with full reference and template
- 1823 tests passing (67 auth-specific)

Author: mnriem

docs/reference/authentication.md

@@ -0,0 +1,181 @@
+# Authentication
+
+Specify CLI uses **opt-in authentication** for HTTP requests to catalog
+sources, extension downloads, and release checks.  No credentials are
+sent unless you explicitly configure them.
+
+## Configuration
+
+Create `~/.specify/auth.json` to enable authentication:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    }
+  ]
+}
+```
+
+> **Security:** Restrict the file to owner-only access:
+> ```
+> chmod 600 ~/.specify/auth.json
+> ```
+
+Without this file, all HTTP requests are unauthenticated.
+
+## Fields
+
+Each entry in the `providers` array has the following fields:
+
+| Field | Required | Description |
+|---|---|---|
+| `hosts` | Yes | Array of hostnames this entry applies to.  Supports wildcards (e.g. `*.visualstudio.com`). |
+| `provider` | Yes | Built-in provider key: `github` or `azure-devops`. |
+| `auth` | Yes | Auth scheme (see below). |
+| `token` | No | Token value (inline). Use `token_env` instead when possible. |
+| `token_env` | No | Environment variable name to read the token from. |
+
+For `azure-ad` auth, additional fields are required:
+
+| Field | Required | Description |
+|---|---|---|
+| `tenant_id` | Yes | Azure AD tenant ID. |
+| `client_id` | Yes | Service principal client ID. |
+| `client_secret_env` | Yes | Environment variable containing the client secret. |
+
+Either `token` or `token_env` must be set for `bearer` and `basic-pat` schemes.
+
+## Providers and auth schemes
+
+### GitHub (`github`)
+
+| Scheme | Header | Use for |
+|---|---|---|
+| `bearer` | `Authorization: Bearer <token>` | PATs, fine-grained PATs, OAuth tokens, GitHub App tokens |
+
+**Example — PAT via environment variable:**
+
+```json
+{
+  "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+  "provider": "github",
+  "auth": "bearer",
+  "token_env": "GH_TOKEN"
+}
+```
+
+### Azure DevOps (`azure-devops`)
+
+| Scheme | Header | Use for |
+|---|---|---|
+| `basic-pat` | `Authorization: Basic base64(:<PAT>)` | Personal Access Tokens |
+| `bearer` | `Authorization: Bearer <token>` | Pre-acquired OAuth / Azure AD tokens |
+| `azure-cli` | `Authorization: Bearer <token>` | Token acquired via `az account get-access-token` |
+| `azure-ad` | `Authorization: Bearer <token>` | Token acquired via OAuth2 client credentials flow |
+
+**Example — PAT via environment variable:**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "basic-pat",
+  "token_env": "AZURE_DEVOPS_PAT"
+}
+```
+
+**Example — Azure CLI (interactive login):**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "azure-cli"
+}
+```
+
+Requires `az login` to have been run beforehand.
+
+**Example — Azure AD service principal (CI/automation):**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "azure-ad",
+  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_secret_env": "AZURE_CLIENT_SECRET"
+}
+```
+
+## Multiple entries
+
+You can configure multiple entries for different hosts or organizations:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    },
+    {
+      "hosts": ["dev.azure.com"],
+      "provider": "azure-devops",
+      "auth": "basic-pat",
+      "token_env": "AZURE_DEVOPS_PAT"
+    }
+  ]
+}
+```
+
+## How it works
+
+1. For each outbound HTTP request, the URL hostname is matched against
+   the `hosts` patterns in `auth.json`.
+2. If a match is found, the corresponding provider resolves the token
+   and attaches the appropriate `Authorization` header.
+3. If the request receives a 401 or 403, the next matching entry is tried.
+4. After all matching entries are exhausted, an unauthenticated request
+   is attempted as a final fallback.
+5. On redirects, the `Authorization` header is stripped if the redirect
+   target leaves the entry's declared hosts — preventing credential
+   leakage to CDNs or third-party services.
+
+## Template
+
+A reference `auth.json` with GitHub pre-configured:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": [
+        "github.com",
+        "api.github.com",
+        "raw.githubusercontent.com",
+        "codeload.github.com"
+      ],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    }
+  ]
+}
+```
+
+To use it:
+
+```bash
+mkdir -p ~/.specify
+# Copy the JSON above into ~/.specify/auth.json
+chmod 600 ~/.specify/auth.json
+```

src/specify_cli/authentication/__init__.py

@@ -1,11 +1,9 @@
 """Authentication provider registry for multi-platform support.
 
-Follows the same pattern as ``src/specify_cli/integrations/``.
-
-Each provider is a self-contained module that handles credential resolution
-and header construction for a specific platform (GitHub, Azure DevOps, etc.).
-Built-in providers are instantiated and added to the global ``AUTH_REGISTRY``
-by ``_register_builtins()``.
+Credentials are **opt-in only**.  No authentication headers are sent unless
+the user creates ``~/.specify/auth.json`` mapping hosts to providers.
+Provider classes define *how* to authenticate (Bearer, Basic-PAT, etc.)
+while the config file defines *where* and *with what credentials*.
 """
 
 from __future__ import annotations
@@ -15,7 +13,7 @@
 if TYPE_CHECKING:
     from .base import AuthProvider
 
-# Maps provider key → AuthProvider instance.
+# Maps provider key → AuthProvider class instance.
 AUTH_REGISTRY: dict[str, AuthProvider] = {}
 
 
@@ -37,21 +35,14 @@ def get_provider(key: str) -> AuthProvider | None:
     return AUTH_REGISTRY.get(key)
 
 
-def configured_providers() -> list[AuthProvider]:
-    """Return all providers that currently have credentials configured."""
-    return [p for p in AUTH_REGISTRY.values() if p.is_configured()]
-
-
 # -- Register built-in providers -----------------------------------------
 
 
 def _register_builtins() -> None:
     """Register all built-in authentication providers (alphabetical)."""
-    # -- Imports (alphabetical) -------------------------------------------
     from .azure_devops import AzureDevOpsAuth
     from .github import GitHubAuth
 
-    # -- Registration (alphabetical) --------------------------------------
     _register(AzureDevOpsAuth())
     _register(GitHubAuth())
 

src/specify_cli/authentication/azure_devops.py

@@ -3,44 +3,114 @@
 from __future__ import annotations
 
 import base64
+import json as _json
 import os
+import subprocess
+from typing import TYPE_CHECKING
 
 from .base import AuthProvider
 
+if TYPE_CHECKING:
+    from .config import AuthConfigEntry
+
+# Azure DevOps resource ID for OAuth / Azure AD token acquisition.
+_ADO_RESOURCE_ID = "499b84ac-1321-427f-aa17-267ca6975798"
+
 
 class AzureDevOpsAuth(AuthProvider):
     """Azure DevOps authentication provider.
 
-    Resolves credentials from ``AZURE_DEVOPS_PAT`` or ``ADO_TOKEN``
-    environment variables, checking ``AZURE_DEVOPS_PAT`` first.
+    Supports four auth schemes:
 
-    Azure DevOps uses HTTP Basic Authentication with an empty username and the
-    Personal Access Token (PAT) as the password.  The credentials are
-    Base64-encoded in the form ``:<PAT>`` as required by the Azure DevOps REST
-    API.
+    * ``basic-pat`` — PAT with empty username, Base64-encoded as ``:<PAT>``
+    * ``bearer`` — pre-acquired OAuth / Azure AD token
+    * ``azure-cli`` — acquires a token via ``az account get-access-token``
+    * ``azure-ad`` — acquires a token via OAuth2 client credentials flow
     """
 
     key = "azure-devops"
+    supported_auth_schemes = ("basic-pat", "bearer", "azure-cli", "azure-ad")
 
-    def get_token(self) -> str | None:
-        """Return the first non-empty PAT from AZURE_DEVOPS_PAT or ADO_TOKEN."""
-        for env_var in ("AZURE_DEVOPS_PAT", "ADO_TOKEN"):
-            candidate = os.environ.get(env_var)
-            if candidate is not None:
-                candidate = candidate.strip()
-                if candidate:
-                    return candidate
-        return None
-
-    def auth_headers(self) -> dict[str, str]:
-        """Return Azure DevOps Basic auth headers, or an empty dict if not configured.
-
-        Azure DevOps REST API requires Basic authentication where the password
-        is the PAT and the username is left empty, encoded as ``:<PAT>`` in
-        Base64.
-        """
-        token = self.get_token()
-        if token:
+    def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:
+        """Build the ``Authorization`` header for the given scheme."""
+        if auth_scheme == "basic-pat":
             encoded = base64.b64encode(f":{token}".encode("ascii")).decode("ascii")
             return {"Authorization": f"Basic {encoded}"}
-        return {}
+        if auth_scheme in ("bearer", "azure-cli", "azure-ad"):
+            return {"Authorization": f"Bearer {token}"}
+        raise ValueError(
+            f"AzureDevOpsAuth does not support auth scheme {auth_scheme!r}"
+        )
+
+    def resolve_token(self, entry: AuthConfigEntry) -> str | None:
+        """Resolve token, with special handling for azure-cli and azure-ad."""
+        if entry.auth == "azure-cli":
+            return self._acquire_via_az_cli()
+        if entry.auth == "azure-ad":
+            return self._acquire_via_client_credentials(entry)
+        return super().resolve_token(entry)
+
+    # -- Token acquisition ------------------------------------------------
+
+    @staticmethod
+    def _acquire_via_az_cli() -> str | None:
+        """Run ``az account get-access-token`` and return the access token."""
+        try:
+            result = subprocess.run(  # noqa: S603, S607
+                [
+                    "az",
+                    "account",
+                    "get-access-token",
+                    "--resource",
+                    _ADO_RESOURCE_ID,
+                    "--output",
+                    "json",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+            if result.returncode != 0:
+                return None
+            payload = _json.loads(result.stdout)
+            token = payload.get("accessToken", "").strip()
+            return token or None
+        except (OSError, _json.JSONDecodeError, KeyError):
+            return None
+
+    @staticmethod
+    def _acquire_via_client_credentials(entry: AuthConfigEntry) -> str | None:
+        """Acquire a token via OAuth2 client credentials flow."""
+        import urllib.error
+        import urllib.request
+
+        if not entry.tenant_id or not entry.client_id or not entry.client_secret_env:
+            return None
+        client_secret = os.environ.get(entry.client_secret_env, "").strip()
+        if not client_secret:
+            return None
+
+        url = (
+            f"https://login.microsoftonline.com/{entry.tenant_id}"
+            "/oauth2/v2.0/token"
+        )
+        body = (
+            f"grant_type=client_credentials"
+            f"&client_id={entry.client_id}"
+            f"&client_secret={client_secret}"
+            f"&scope={_ADO_RESOURCE_ID}/.default"
+        ).encode("utf-8")
+
+        req = urllib.request.Request(
+            url,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310
+                payload = _json.loads(resp.read().decode("utf-8"))
+                token = payload.get("access_token", "").strip()
+                return token or None
+        except (urllib.error.URLError, OSError, _json.JSONDecodeError, KeyError):
+            return None