vercel-oidc 0.6.0__tar.gz

vercel_oidc-0.6.0/.gitignore

@@ -0,0 +1,128 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_oidc-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+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.

vercel_oidc-0.6.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: vercel-oidc
+Version: 0.6.0
+Summary: OIDC helpers for Vercel Python applications
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: vercel-headers>=0.6.0
+Description-Content-Type: text/markdown
+
+# OIDC
+
+`vercel.oidc` retrieves and decodes Vercel OIDC tokens.
+
+## Async Token Lookup
+
+```python
+from vercel.oidc import decode_oidc_payload
+from vercel.headers import set_headers
+from vercel.oidc.aio import get_vercel_oidc_token
+
+
+async def main() -> None:
+    token = await get_vercel_oidc_token()
+    payload = decode_oidc_payload(token)
+    project_id = payload.get("project_id")
+```
+
+Token lookup prefers the `x-vercel-oidc-token` request header registered with
+`vercel.headers.set_headers()`, then `VERCEL_OIDC_TOKEN`. The compatibility
+alias `vercel.oidc.set_headers()` updates the same header context. In local development,
+you can load a short-lived token dynamically:
+
+```bash
+VERCEL_OIDC_TOKEN=$(vc project token some-project) some-command
+```
+
+Use `vercel.oidc.get_vercel_oidc_token()` for synchronous code.

vercel_oidc-0.6.0/README.md

@@ -0,0 +1,28 @@
+# OIDC
+
+`vercel.oidc` retrieves and decodes Vercel OIDC tokens.
+
+## Async Token Lookup
+
+```python
+from vercel.oidc import decode_oidc_payload
+from vercel.headers import set_headers
+from vercel.oidc.aio import get_vercel_oidc_token
+
+
+async def main() -> None:
+    token = await get_vercel_oidc_token()
+    payload = decode_oidc_payload(token)
+    project_id = payload.get("project_id")
+```
+
+Token lookup prefers the `x-vercel-oidc-token` request header registered with
+`vercel.headers.set_headers()`, then `VERCEL_OIDC_TOKEN`. The compatibility
+alias `vercel.oidc.set_headers()` updates the same header context. In local development,
+you can load a short-lived token dynamically:
+
+```bash
+VERCEL_OIDC_TOKEN=$(vc project token some-project) some-command
+```
+
+Use `vercel.oidc.get_vercel_oidc_token()` for synchronous code.

vercel_oidc-0.6.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vercel-oidc"
+dynamic = ["version"]
+description = "OIDC helpers for Vercel Python applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSE.*"]
+dependencies = [
+    "httpx>=0.27.0,<1",
+    "vercel-headers>=0.6.0",
+]
+
+[tool.uv.sources]
+vercel-headers = { workspace = true }
+
+[tool.hatch.version]
+path = "vercel/oidc/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/vercel/oidc/**/*.py",
+    "/README.md",
+    "/vercel/oidc/py.typed",
+    "/pyproject.toml",
+    "/LICENSE",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+dev-mode-dirs = ["."]
+only-include = ["/vercel/oidc"]
+exclude = [
+    "/**/__pycache__",
+]

vercel_oidc-0.6.0/vercel/oidc/__init__.py

@@ -0,0 +1,21 @@
+from vercel.headers import set_headers
+
+from .credentials import Credentials, get_credentials
+from .token import (
+    VercelOidcTokenError,
+    decode_oidc_payload,
+    get_token_payload,
+    get_vercel_oidc_token,
+    get_vercel_oidc_token_sync,
+)
+
+__all__ = [
+    "VercelOidcTokenError",
+    "get_vercel_oidc_token",
+    "get_vercel_oidc_token_sync",
+    "get_token_payload",
+    "set_headers",
+    "Credentials",
+    "get_credentials",
+    "decode_oidc_payload",
+]

vercel_oidc-0.6.0/vercel/oidc/aio.py

@@ -0,0 +1,7 @@
+from .token import (
+    fetch_vercel_oidc_token_async as fetch_vercel_oidc_token,
+    get_vercel_oidc_token_async as get_vercel_oidc_token,
+    refresh_token_async as refresh_token,
+)
+
+__all__ = ["get_vercel_oidc_token", "refresh_token", "fetch_vercel_oidc_token"]

vercel_oidc-0.6.0/vercel/oidc/credentials.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+
+from .token import VercelOidcTokenError, decode_oidc_payload, get_vercel_oidc_token_from_context
+from .types import Credentials
+
+
+def get_credentials(
+    *,
+    token: str | None = None,
+    project_id: str | None = None,
+    team_id: str | None = None,
+) -> Credentials:
+    if token and project_id and team_id:
+        return Credentials(token=token, project_id=project_id, team_id=team_id)
+
+    # Resolve OIDC token from request headers (set by the runtime) or env var.
+    oidc: str | None = None
+    try:
+        oidc = get_vercel_oidc_token_from_context()
+    except VercelOidcTokenError:
+        pass
+
+    if oidc:
+        project = os.getenv("VERCEL_PROJECT_ID")
+        team = os.getenv("VERCEL_TEAM_ID")
+        if not (project and team):
+            try:
+                payload = decode_oidc_payload(oidc)
+                project = payload.get("project_id")
+                team = payload.get("owner_id")
+            except Exception:
+                pass
+        if project and team:
+            return Credentials(token=oidc, project_id=project, team_id=team)
+        raise RuntimeError(
+            "OIDC token present but could not determine VERCEL_PROJECT_ID and VERCEL_TEAM_ID"
+        )
+
+    token = token or os.getenv("VERCEL_TOKEN")
+    project_id = project_id or os.getenv("VERCEL_PROJECT_ID")
+    team_id = team_id or os.getenv("VERCEL_TEAM_ID")
+
+    if token and project_id and team_id:
+        return Credentials(token=token, project_id=project_id, team_id=team_id)
+
+    raise RuntimeError(
+        "Missing credentials. "
+        "For local development, run 'vercel link && vercel env pull'. "
+        "Otherwise, set VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_TEAM_ID."
+    )

vercel_oidc-0.6.0/vercel/oidc/token.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+import httpx
+
+from vercel.headers import get_headers
+
+from .types import VercelTokenResponse
+from .utils import (
+    find_project_info,
+    get_token_payload,
+    get_vercel_cli_token,
+    is_expired,
+    load_token,
+    save_token,
+)
+
+BASE_URL = "https://api.vercel.com/v1"
+
+
+class VercelOidcTokenError(Exception):
+    def __init__(self, message: str, cause: Exception | None = None):
+        if cause is not None:
+            message = f"{message}: {cause}"
+        super().__init__(message)
+        self.cause = cause
+
+
+def get_vercel_oidc_token_from_context() -> str:
+    # Prefer request header registered in the OIDC context,
+    # fall back to environment variable like the TypeScript SDK.
+    headers = get_headers()
+    if headers:
+        # Normalize headers to lowercase keys
+        lower_headers: dict[str, str] = {}
+        if isinstance(headers, Mapping):
+            for k, v in headers.items():
+                lower_headers[str(k).lower()] = v
+        elif isinstance(headers, (list, tuple)):
+            for item in headers:
+                if isinstance(item, (list, tuple)) and len(item) == 2:
+                    k, v = item
+                    lower_headers[str(k).lower()] = v
+        elif hasattr(headers, "keys") and hasattr(headers, "__getitem__"):
+            for k in headers.keys():
+                v = headers[k]
+                lower_headers[str(k).lower()] = v
+
+        token_from_header = lower_headers.get("x-vercel-oidc-token")
+        if token_from_header:
+            return token_from_header
+
+    token_from_env = os.getenv("VERCEL_OIDC_TOKEN")
+    if not token_from_env:
+        raise VercelOidcTokenError(
+            "The 'x-vercel-oidc-token' header is missing from the request. "
+            "Do you have the OIDC option enabled in the Vercel project settings?"
+        )
+    return token_from_env
+
+
+# for TS parity
+get_vercel_oidc_token_sync = get_vercel_oidc_token_from_context
+
+
+def refresh_token() -> None:
+    project = find_project_info()
+    project_id: str = project["projectId"]
+    team_id = project.get("teamId")
+
+    maybe = load_token(project_id)
+    if not maybe or is_expired(get_token_payload(maybe.token)):
+        auth_token = get_vercel_cli_token()
+        if not auth_token:
+            raise VercelOidcTokenError("Failed to refresh OIDC token: login to vercel cli")
+        if not project_id:
+            raise VercelOidcTokenError("Failed to refresh OIDC token: project id not found")
+        new_token = fetch_vercel_oidc_token(auth_token, project_id, team_id)
+        if not new_token:
+            raise VercelOidcTokenError("Failed to refresh OIDC token")
+        save_token(new_token, project_id)
+        os.environ["VERCEL_OIDC_TOKEN"] = new_token.token
+    else:
+        os.environ["VERCEL_OIDC_TOKEN"] = maybe.token
+
+
+async def refresh_token_async() -> None:
+    project = find_project_info()
+    project_id: str = project["projectId"]
+    team_id = project.get("teamId")
+
+    maybe = load_token(project_id)
+    if not maybe or is_expired(get_token_payload(maybe.token)):
+        auth_token = get_vercel_cli_token()
+        if not auth_token:
+            raise VercelOidcTokenError("Failed to refresh OIDC token: login to vercel cli")
+        if not project_id:
+            raise VercelOidcTokenError("Failed to refresh OIDC token: project id not found")
+        new_token = await fetch_vercel_oidc_token_async(auth_token, project_id, team_id)
+        if not new_token:
+            raise VercelOidcTokenError("Failed to refresh OIDC token")
+        save_token(new_token, project_id)
+        os.environ["VERCEL_OIDC_TOKEN"] = new_token.token
+    else:
+        os.environ["VERCEL_OIDC_TOKEN"] = maybe.token
+
+
+def get_vercel_oidc_token() -> str:
+    token = ""
+    err: Exception | None = None
+    try:
+        token = get_vercel_oidc_token_from_context()
+    except Exception as e:
+        err = e
+    try:
+        if not token or is_expired(get_token_payload(token)):
+            # Only attempt refresh in environments that look like local dev with a .vercel folder
+            try:
+                _ = find_project_info()
+            except Exception as e:
+                # Preserve the original context error and surface an actionable message
+                if err and isinstance(err, Exception) and getattr(err, "message", None):
+                    e.args = (f"{err}\n{e}",)
+                raise VercelOidcTokenError(
+                    "Missing OIDC request header and no local project context (.vercel) available",
+                    e,
+                ) from e
+            refresh_token()
+            token = get_vercel_oidc_token_from_context()
+    except Exception as e:
+        if err and isinstance(e, Exception) and getattr(err, "message", None):
+            e.args = (f"{err}\n{e}",)
+        raise VercelOidcTokenError("Failed to refresh OIDC token", e) from e
+    return token
+
+
+async def get_vercel_oidc_token_async() -> str:
+    token = ""
+    err: Exception | None = None
+    try:
+        token = get_vercel_oidc_token_from_context()
+    except Exception as e:
+        err = e
+    try:
+        if not token or is_expired(get_token_payload(token)):
+            # Only attempt refresh in environments that look like local dev with a .vercel folder
+            try:
+                _ = find_project_info()
+            except Exception as e:
+                if err and isinstance(err, Exception) and getattr(err, "message", None):
+                    e.args = (f"{err}\n{e}",)
+                raise VercelOidcTokenError(
+                    "Missing OIDC request header and no local project context (.vercel) available",
+                    e,
+                ) from e
+            await refresh_token_async()
+            token = get_vercel_oidc_token_from_context()
+    except Exception as e:
+        if err and isinstance(e, Exception) and getattr(err, "message", None):
+            e.args = (f"{err}\n{e}",)
+        raise VercelOidcTokenError("Failed to refresh OIDC token", e) from e
+    return token
+
+
+def fetch_vercel_oidc_token(
+    auth_token: str, project_id: str, team_id: str | None
+) -> VercelTokenResponse | None:
+    url = f"{BASE_URL}/projects/{project_id}/token?source=vercel-oidc-refresh"
+    if team_id:
+        url += f"&teamId={team_id}"
+    with httpx.Client(timeout=httpx.Timeout(30.0)) as client:
+        r = client.post(url, headers={"authorization": f"Bearer {auth_token}"})
+        if not (200 <= r.status_code < 300):
+            raise RuntimeError(f"Failed to refresh OIDC token: {r.status_code} {r.reason_phrase}")
+        data = r.json()
+        if not isinstance(data, dict) or not isinstance(data.get("token"), str):
+            raise TypeError("Expected a string-valued token property")
+        return VercelTokenResponse(token=data["token"])
+
+
+async def fetch_vercel_oidc_token_async(
+    auth_token: str, project_id: str, team_id: str | None
+) -> VercelTokenResponse | None:
+    url = f"{BASE_URL}/projects/{project_id}/token?source=vercel-oidc-refresh"
+    if team_id:
+        url += f"&teamId={team_id}"
+    async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+        r = await client.post(url, headers={"authorization": f"Bearer {auth_token}"})
+        if not (200 <= r.status_code < 300):
+            raise RuntimeError(f"Failed to refresh OIDC token: {r.status_code} {r.reason_phrase}")
+        data = r.json()
+        if not isinstance(data, dict) or not isinstance(data.get("token"), str):
+            raise TypeError("Expected a string-valued token property")
+        return VercelTokenResponse(token=data["token"])
+
+
+def decode_oidc_payload(token: str) -> dict:
+    return get_token_payload(token)

vercel_oidc-0.6.0/vercel/oidc/types.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypedDict
+
+
+class ProjectInfo(TypedDict):
+    projectId: str
+    teamId: str | None
+
+
+@dataclass
+class VercelTokenResponse:
+    token: str
+
+
+@dataclass
+class Credentials:
+    token: str
+    project_id: str
+    team_id: str

vercel_oidc-0.6.0/vercel/oidc/utils.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+from typing import Any
+
+from .types import ProjectInfo, VercelTokenResponse
+
+
+def _user_data_dir() -> str | None:
+    try:
+        home = os.path.expanduser("~")
+        if sys.platform.startswith("win"):
+            # Prefer LOCALAPPDATA for application data storage on Windows
+            return os.environ.get("LOCALAPPDATA")
+        if sys.platform == "darwin":
+            return os.path.join(home, "Library", "Application Support")
+        # linux and others
+        xdg_data_home = os.environ.get("XDG_DATA_HOME")
+        return xdg_data_home or os.path.join(home, ".local", "share")
+    except Exception:
+        return None
+
+
+def get_vercel_data_dir() -> str | None:
+    base = _user_data_dir()
+    if not base:
+        return None
+    return os.path.join(base, "com.vercel.cli")
+
+
+def get_vercel_cli_token() -> str | None:
+    data_dir = get_vercel_data_dir()
+    if not data_dir:
+        return None
+    token_path = os.path.join(data_dir, "auth.json")
+    if not os.path.exists(token_path):
+        return None
+    try:
+        with open(token_path, encoding="utf-8") as f:
+            data = json.load(f)
+        token = data.get("token")
+        if isinstance(token, str) and token:
+            return token
+        return None
+    except Exception:
+        return None
+
+
+def _find_root_dir(start: str | None = None) -> str | None:
+    # Walk up from start (or cwd) looking for a .vercel folder (align with TS SDK)
+    current = os.path.abspath(start or os.getcwd())
+    while True:
+        vercel_dir = os.path.join(current, ".vercel")
+        if os.path.isdir(vercel_dir):
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def find_project_info() -> ProjectInfo:
+    root = _find_root_dir()
+    if not root:
+        raise RuntimeError("Unable to find root directory")
+    prj_path = os.path.join(root, ".vercel", "project.json")
+    if not os.path.exists(prj_path):
+        raise RuntimeError("project.json not found")
+    try:
+        with open(prj_path, encoding="utf-8") as f:
+            prj = json.load(f)
+        project_id = prj.get("projectId")
+        team_id = prj.get("orgId") if isinstance(prj.get("orgId"), str) else None
+        if not isinstance(project_id, str):
+            raise TypeError("Expected a string-valued projectId property")
+        return {"projectId": project_id, "teamId": team_id}
+    except Exception as e:
+        raise RuntimeError("Unable to find project ID") from e
+
+
+def _token_store_dir() -> str | None:
+    base = _user_data_dir()
+    if not base:
+        return None
+    return os.path.join(base, "com.vercel.token")
+
+
+def save_token(token: VercelTokenResponse, project_id: str) -> None:
+    directory = _token_store_dir()
+    if not directory:
+        raise RuntimeError("Unable to find user data directory")
+    try:
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+        token_path = os.path.join(directory, f"{project_id}.json")
+        with open(token_path, "w", encoding="utf-8") as f:
+            json.dump({"token": token.token}, f)
+        try:
+            os.chmod(token_path, 0o600)
+        except Exception:
+            pass
+    except Exception as e:
+        raise RuntimeError("Failed to save token") from e
+
+
+def load_token(project_id: str) -> VercelTokenResponse | None:
+    directory = _token_store_dir()
+    if not directory:
+        return None
+    token_path = os.path.join(directory, f"{project_id}.json")
+    if not os.path.exists(token_path):
+        return None
+    try:
+        with open(token_path, encoding="utf-8") as f:
+            data = json.load(f)
+        token = data.get("token")
+        if isinstance(token, str):
+            return VercelTokenResponse(token=token)
+        return None
+    except Exception as e:
+        raise RuntimeError("Failed to load token") from e
+
+
+def get_token_payload(token: str) -> dict[str, Any]:
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("Invalid token")
+    base64_part = parts[1].replace("-", "+").replace("_", "/")
+    padded = base64_part + "=" * ((4 - (len(base64_part) % 4)) % 4)
+    decoded = base64.b64decode(padded)
+    return json.loads(decoded.decode("utf-8"))
+
+
+def is_expired(payload: dict[str, Any]) -> bool:
+    # Consider token expired if it will expire within the next 15 minutes
+    exp = payload.get("exp")
+    if not isinstance(exp, (int, float)):
+        return True
+    import time
+
+    fifteen_minutes_ms = 15 * 60 * 1000
+    now_ms = int(time.time() * 1000)
+    return int(exp * 1000) < now_ms + fifteen_minutes_ms

vercel_oidc-0.6.0/vercel/oidc/version.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"