diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/auth.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/auth.py new file mode 100644 index 00000000000..f963045d016 --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/auth.py @@ -0,0 +1,60 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Authentication protocols and helpers for NemoClient. + +Defines the protocols that any token provider must satisfy, plus simple +concrete implementations. + +OIDC-specific machinery lives in :mod:`~.oidc` (token provider, token set, +discovery) and :mod:`~.oidc_factory` (provider caching, config persistence). +""" + +from __future__ import annotations + +from typing import Protocol, runtime_checkable + +# --------------------------------------------------------------------------- +# Protocols +# --------------------------------------------------------------------------- + + +@runtime_checkable +class TokenProvider(Protocol): + """Sync protocol for objects that can supply an access token.""" + + def get_access_token(self) -> str: ... + + +@runtime_checkable +class AsyncTokenProvider(Protocol): + """Async protocol for objects that can supply an access token.""" + + async def get_access_token(self) -> str: ... + + +# --------------------------------------------------------------------------- +# StaticToken +# --------------------------------------------------------------------------- + + +class StaticToken: + """Wraps a plain token string into a TokenProvider.""" + + def __init__(self, token: str) -> None: + self._token = token + + def get_access_token(self) -> str: + return self._token + + async def get_access_token_async(self) -> str: + return self._token + + +# --------------------------------------------------------------------------- +# Auth errors +# --------------------------------------------------------------------------- + + +class AuthError(Exception): + """Authentication-related error.""" diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/client.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/client.py index 4ee332ed62d..f337dd200ac 100644 --- a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/client.py +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/client.py @@ -17,11 +17,17 @@ from __future__ import annotations import asyncio +import inspect import time from collections.abc import Mapping +from pathlib import Path from typing import Any, TypeVar, get_args, get_origin, overload import httpx +from nemo_platform_plugin.client.auth import ( + StaticToken, + TokenProvider, +) from nemo_platform_plugin.client.response import ( AsyncNemoBinaryResponse, AsyncNemoPaginatedResponse, @@ -107,10 +113,12 @@ def __init__( *, base_url: str, workspace: str | None = None, + auth: TokenProvider | str | None = None, retry: RetryPolicy | None = None, ) -> None: self._base_url = base_url.rstrip("/") self._workspace = workspace + self._auth: TokenProvider | None = StaticToken(auth) if isinstance(auth, str) else auth self._retry = retry @property @@ -202,12 +210,13 @@ def __init__( *, base_url: str, workspace: str | None = None, + auth: TokenProvider | str | None = None, default_headers: Mapping[str, str] | None = None, timeout: float = DEFAULT_TIMEOUT, retry: RetryPolicy | None = None, http_client: httpx.Client | None = None, ) -> None: - super().__init__(base_url=base_url, workspace=workspace, retry=retry) + super().__init__(base_url=base_url, workspace=workspace, auth=auth, retry=retry) self._http = http_client or httpx.Client( headers=dict(default_headers) if default_headers else None, timeout=timeout, @@ -254,6 +263,20 @@ def send( retry: RetryPolicy | None = None, ) -> NemoResponse[ResponseT]: ... + @classmethod + def from_config( + cls, + context: str | None = None, + config_path: Path | str | None = None, + ) -> NemoClient: + """Create a NemoClient from the user's nmp config file. + + Args: + context: Context name to use (default: active context). + config_path: Path to config file (default: ``~/.config/nmp/config.yaml``). + """ + return _client_from_config(cls, context=context, config_path=config_path) + def send( self, request: PreparedRequest, @@ -280,6 +303,14 @@ def send( if headers: request = request.with_headers(headers) + # Inject auth header if a TokenProvider is configured. + # NOTE: If a 401 occurs despite this, a future enhancement could + # call provider.force_refresh() and retry once. The proactive + # refresh margin (60s) makes this unlikely in practice. + if self._auth: + token = self._auth.get_access_token() + request = request.with_headers({"Authorization": f"Bearer {token}"}) + url = self._resolve_path(request) req_headers = self._request_headers(request) params = self._resolve_query_params(request) @@ -371,12 +402,13 @@ def __init__( *, base_url: str, workspace: str | None = None, + auth: TokenProvider | str | None = None, default_headers: Mapping[str, str] | None = None, timeout: float = DEFAULT_TIMEOUT, retry: RetryPolicy | None = None, http_client: httpx.AsyncClient | None = None, ) -> None: - super().__init__(base_url=base_url, workspace=workspace, retry=retry) + super().__init__(base_url=base_url, workspace=workspace, auth=auth, retry=retry) self._http = http_client or httpx.AsyncClient( headers=dict(default_headers) if default_headers else None, timeout=timeout, @@ -423,6 +455,20 @@ async def send( retry: RetryPolicy | None = None, ) -> NemoResponse[ResponseT]: ... + @classmethod + def from_config( + cls, + context: str | None = None, + config_path: Path | str | None = None, + ) -> AsyncNemoClient: + """Create an AsyncNemoClient from the user's nmp config file. + + Args: + context: Context name to use (default: active context). + config_path: Path to config file (default: ``~/.config/nmp/config.yaml``). + """ + return _client_from_config(cls, context=context, config_path=config_path) + async def send( self, request: PreparedRequest, @@ -434,6 +480,21 @@ async def send( if headers: request = request.with_headers(headers) + # Inject auth header. Three cases, in priority order: + # 1. Provider has get_access_token_async() (e.g. OIDCTokenProvider) — use it. + # 2. Provider.get_access_token() is a coroutine function — await it. + # 3. Provider.get_access_token() is sync — run in a thread to avoid + # blocking the event loop during IO (e.g. token refresh HTTP calls). + if self._auth: + get_async = getattr(self._auth, "get_access_token_async", None) + if get_async is not None and callable(get_async): + token = await get_async() + elif inspect.iscoroutinefunction(self._auth.get_access_token): + token = await self._auth.get_access_token() + else: + token = await asyncio.to_thread(self._auth.get_access_token) + request = request.with_headers({"Authorization": f"Bearer {token}"}) + url = self._resolve_path(request) req_headers = self._request_headers(request) params = self._resolve_query_params(request) @@ -514,3 +575,56 @@ async def fetch(request: PreparedRequest, page: int | str) -> httpx.Response: return await self._request_with_retry(request, url, req_headers, params, retry) return fetch + + +# --------------------------------------------------------------------------- +# from_config helper (shared by NemoClient and AsyncNemoClient) +# --------------------------------------------------------------------------- + +_ClientT = TypeVar("_ClientT", NemoClient, AsyncNemoClient) + + +def _client_from_config( + cls: type[_ClientT], + *, + context: str | None = None, + config_path: Path | str | None = None, +) -> _ClientT: + """Shared implementation for NemoClient.from_config / AsyncNemoClient.from_config.""" + from nemo_platform_plugin.client.config.config import Config + from nemo_platform_plugin.client.config.models import ConfigParams, OAuthUser + from nemo_platform_plugin.client.oidc_factory import resolve_oidc_provider + + resolved_path = Path(config_path) if isinstance(config_path, str) else config_path + overrides: ConfigParams | None = None + if context is not None: + overrides = {"current_context": context} + config = Config.load(config_path=resolved_path, overrides=overrides) + actual_config_path = config.get_config_path() or Config.get_default_config_path() + config_exists = actual_config_path.exists() + # If the token came from NMP_ACCESS_TOKEN (env override), it's not from + # the config file — don't cache or persist provider state for it. + explicit_access_token = config.access_token is not None + ctx = config.resolve() + + auth: TokenProvider | str | None = None + + if isinstance(ctx.user, OAuthUser): + auth = resolve_oidc_provider( + base_url=str(ctx.cluster.base_url), + context_name=ctx.context_name, + access_token=ctx.user.token.get_secret_value(), + refresh_token=ctx.user.refresh_token.get_secret_value() if ctx.user.refresh_token else None, + config_exists=config_exists, + config_path=actual_config_path, + explicit_access_token=explicit_access_token, + ) + elif ctx.user: + client_config = ctx.user.get_client_config() + raw_headers = client_config.get("default_headers") + if isinstance(raw_headers, dict): + raw_auth = dict(raw_headers).get("Authorization") + if isinstance(raw_auth, str) and raw_auth.startswith("Bearer "): + auth = raw_auth.removeprefix("Bearer ") + + return cls(base_url=str(ctx.cluster.base_url), workspace=ctx.workspace, auth=auth) diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/config.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/config.py new file mode 100644 index 00000000000..b782f93e8ee --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/config.py @@ -0,0 +1,390 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Configuration manager for NemoClient. + +Reads ``~/.config/nmp/config.yaml`` (the user-facing CLI/SDK config) and +resolves clusters, users, and contexts into a :class:`Context` object that +``NemoClient.from_config()`` uses to construct an authenticated client. + +This is distinct from the server-side config in +:mod:`nemo_platform_plugin.config` which reads ``/etc/nmp/config.yaml``. +""" + +from __future__ import annotations + +import logging +import os +import stat +from pathlib import Path + +import yaml +from pydantic import BaseModel, Field, HttpUrl, PrivateAttr, SecretStr +from typing_extensions import Self + +from .models import ( + DEFAULT_BASE_URL, + DEFAULT_CONTEXT, + DEFAULT_WORKSPACE, + ConfigFile, + ConfigParams, + Context, + OAuthUser, + OutputFormat, + TimestampFormat, +) + +logger = logging.getLogger(__name__) + + +class Config(BaseModel): + """Configuration manager for NemoClient. + + Manages the user-facing config file (``~/.config/nmp/config.yaml``), + runtime overrides (env vars, CLI flags, SDK params), and resolution + of effective configuration. + + Environment variables (prefix ``NMP_``):: + + NMP_CURRENT_CONTEXT, NMP_WORKSPACE, NMP_OUTPUT_FORMAT, + NMP_TIMESTAMP_FORMAT, NMP_COLOR_OUTPUT, NMP_BASE_URL, NMP_ACCESS_TOKEN + """ + + current_context: str | None = Field(default=None, description="Override current context (env: NMP_CURRENT_CONTEXT)") + base_url: str | None = Field(default=None, description="Base URL for the API (env: NMP_BASE_URL)") + access_token: SecretStr | None = Field( + default=None, + description="Access token for authentication (env: NMP_ACCESS_TOKEN)", + ) + workspace: str | None = Field(default=None, description="Override workspace (env: NMP_WORKSPACE)") + output_format: OutputFormat | None = Field( + default=None, description="Override output format (env: NMP_OUTPUT_FORMAT)" + ) + timestamp_format: TimestampFormat | None = Field( + default=None, description="Override timestamp format (env: NMP_TIMESTAMP_FORMAT)" + ) + truncate: bool | None = Field(default=None, description="Override truncate config (env: NMP_TRUNCATE)") + color_output: bool | None = Field(default=None, description="Override color output (env: NMP_COLOR_OUTPUT)") + + _config_file: ConfigFile = PrivateAttr(default_factory=ConfigFile) + _config_path: Path | None = PrivateAttr(default=None) + + @classmethod + def _migrate_legacy_api_key_users(cls, config_data: dict) -> None: + """Migrate legacy api-key users to oauth users.""" + users = config_data.get("users") + if not isinstance(users, list): + return + + migrated_count = 0 + + for user in users: + if not isinstance(user, dict): + continue + + user_name = user.get("name", DEFAULT_CONTEXT) + user_type = user.get("type") + if user_type != "api-key" and "api_key" not in user: + continue + + raw_value = user.get("api_key") + if not isinstance(raw_value, str) or not raw_value.strip(): + user.clear() + user.update({"name": user_name, "type": "no-auth"}) + migrated_count += 1 + continue + + token = raw_value.strip() + if "@" in token: + from nemo_platform_plugin.client.oidc import generate_unsigned_jwt + + token = generate_unsigned_jwt( + principal_id=token, + email=token, + expires_in_seconds=None, + ) + + user.clear() + user.update( + { + "name": user_name, + "type": "oauth", + "token": token, + "refresh_token": None, + } + ) + migrated_count += 1 + + if migrated_count: + logger.warning("Migrated %s legacy api-key user(s) to oauth users", migrated_count) + + @classmethod + def _load_from_env(cls) -> dict[str, object]: + """Load configuration from environment variables with NMP_ prefix.""" + env_values: dict[str, object] = {} + for field_name in cls.model_fields: + env_key = f"NMP_{field_name.upper()}" + if val := os.environ.get(env_key): + env_values[field_name] = val + return env_values + + @classmethod + def get_default_config_path(cls) -> Path: + """Get the default configuration file path. + + Can be overridden with ``NMP_CONFIG_FILE`` environment variable. + """ + env_config_path = os.environ.get("NMP_CONFIG_FILE") + if env_config_path: + return Path(env_config_path) + + xdg_config_home = os.environ.get("XDG_CONFIG_HOME") + if xdg_config_home: + return Path(xdg_config_home) / "nmp" / "config.yaml" + + config_dir = Path.home() / ".config" / "nmp" + return config_dir / "config.yaml" + + @classmethod + def create(cls, config_path: Path, config_file: ConfigFile, overrides: ConfigParams | None = None) -> Self: + env_values = cls._load_from_env() + merged: dict[str, object] = {**env_values} + if overrides: + merged.update(dict(overrides)) + + config = cls.model_validate(merged) + config._config_file = config_file + config._config_path = config_path + return config + + @classmethod + def load( + cls, + config_path: Path | None = None, + overrides: ConfigParams | None = None, + ) -> Self: + """Load configuration from config file with optional parameters.""" + explicit_path_param = config_path is not None + env_var_set = os.environ.get("NMP_CONFIG_FILE") is not None + + if config_path is None: + config_path = cls.get_default_config_path() + + config_data = {} + if config_path.exists(): + with open(config_path) as f: + try: + config_data = yaml.safe_load(f) or {} + except yaml.YAMLError as e: + raise ValueError(f"Error parsing config file at {config_path}: {e}") from e + + cls._migrate_legacy_api_key_users(config_data) + elif explicit_path_param or env_var_set: + raise FileNotFoundError(f"Config file not found at {config_path}") + + config_file = ConfigFile.model_validate(config_data) + return cls.create(config_path, config_file, overrides) + + def get_config_file(self) -> ConfigFile: + return self._config_file + + def get_config_path(self) -> Path | None: + return self._config_path + + def save(self, config_path: Path | None = None) -> None: + """Save the current config file to disk.""" + path = config_path or self._config_path or self.get_default_config_path() + + path.parent.mkdir(parents=True, exist_ok=True) + os.chmod(path.parent, stat.S_IRWXU) # 700 + + config_data = self._config_file.model_dump( + mode="json", + exclude_none=True, + context={"include_secrets": True}, + ) + + # Open with restricted permissions (0600) before writing secrets. + # Uses os.open + os.fdopen to set permissions atomically at creation, + # avoiding a window where the file is world-readable. + fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR) + with os.fdopen(fd, "w") as f: + yaml.safe_dump(config_data, f, default_flow_style=False, sort_keys=False) + + self._config_path = path + + @classmethod + def write( + cls, + params: ConfigParams, + context_name: str | None = None, + config_path: Path | None = None, + *, + set_current_on_create: bool = False, + ) -> Self: + """Write configuration settings. Creates the config file if it doesn't exist.""" + path = config_path or cls.get_default_config_path() + + if path.exists(): + config = cls.load(config_path=path) + # Prefer explicit context_name, then params["current_context"], + # then the currently active context from the config file. + context_name = context_name or params.get("current_context") or config.resolve().context_name + else: + config = cls.create(path, ConfigFile()) + context_name = context_name or DEFAULT_CONTEXT + + config_file = config._config_file + + is_new = context_name not in {c.name for c in config_file.contexts} + config_file.ensure_context(context_name, params) + + if "current_context" in params: + config_file.current_context = params["current_context"] + elif config_file.current_context is None or (set_current_on_create and is_new): + config_file.current_context = context_name + + config.save() + return config + + def set_current_context(self, context_name: str) -> None: + """Set the current context in the config file and save.""" + context_names = [ctx.name for ctx in self._config_file.contexts] + if context_name not in context_names: + available = ", ".join(context_names) if context_names else "(none)" + raise ValueError(f"Context '{context_name}' not found. Available contexts: {available}") + + self._config_file.current_context = context_name + self.save() + + def reload(self) -> None: + """Reload configuration from file (preserving runtime parameters).""" + if self._config_path: + current_overrides = self.get_runtime_overrides() + new_config = self.load(config_path=self._config_path, overrides=current_overrides) + + self._config_file = new_config._config_file + self.current_context = new_config.current_context + self.base_url = new_config.base_url + self.access_token = new_config.access_token + self.workspace = new_config.workspace + self.output_format = new_config.output_format + self.timestamp_format = new_config.timestamp_format + self.truncate = new_config.truncate + self.color_output = new_config.color_output + + def resolve(self) -> Context: + """Resolve the effective configuration by applying context and overrides.""" + if not self._config_file.contexts: + return self._create_default_config() + + context_name = self.current_context or self._config_file.current_context or DEFAULT_CONTEXT + + context = None + for ctx in self._config_file.contexts: + if ctx.name == context_name: + context = ctx + break + + if context is None: + available_contexts = [ctx.name for ctx in self._config_file.contexts] + raise ValueError(f"Context '{context_name}' not found. Available contexts: {', '.join(available_contexts)}") + + cluster = None + for clus in self._config_file.clusters: + if clus.name == context.cluster: + cluster = clus + break + + if cluster is None: + raise ValueError(f"Cluster '{context.cluster}' referenced by context '{context_name}' not found") + + user = None + for usr in self._config_file.users: + if usr.name == context.user: + user = usr + break + + if user is None: + raise ValueError(f"User '{context.user}' referenced by context '{context_name}' not found") + + prefs = context.preferences.model_copy(deep=True) + + if self.base_url is not None: + cluster.base_url = HttpUrl(self.base_url) + if self.access_token is not None: + user = OAuthUser( + name=user.name, + token=self.access_token, + refresh_token=None, + ) + if self.output_format is not None: + prefs.output_format = self.output_format + if self.timestamp_format is not None: + prefs.timestamp_format = self.timestamp_format + if self.truncate is not None: + prefs.truncate = self.truncate + if self.color_output is not None: + prefs.color_output = self.color_output + + effective_workspace = self.workspace if self.workspace is not None else context.workspace + if effective_workspace is None: + effective_workspace = DEFAULT_WORKSPACE + + effective_default_model = os.environ.get("NEMO_DEFAULT_MODEL") or context.default_model + + return Context( + context_name=context_name, + cluster=cluster, + user=user, + workspace=effective_workspace, + default_model=effective_default_model, + preferences=prefs, + ) + + def get_runtime_overrides(self) -> ConfigParams: + result: ConfigParams = {} + result.update(self.model_dump(exclude_unset=True)) + return result + + def _create_default_config(self) -> Context: + base_url = self.base_url or DEFAULT_BASE_URL + + params: ConfigParams = {"base_url": base_url} + if self.access_token: + params["access_token"] = self.access_token.get_secret_value() + if self.workspace: + params["workspace"] = self.workspace + if self.output_format is not None: + params["output_format"] = self.output_format + if self.timestamp_format is not None: + params["timestamp_format"] = self.timestamp_format + if self.truncate is not None: + params["truncate"] = self.truncate + + context_name = self.current_context or "default" + + cluster, user, context_def = self._config_file.ensure_context(context_name, params) + self._config_file.current_context = context_name + + prefs = context_def.preferences.model_copy(deep=True) + if self.color_output is not None: + prefs.color_output = self.color_output + + return Context( + context_name=context_name, + cluster=cluster, + user=user, + workspace=context_def.workspace or DEFAULT_WORKSPACE, + default_model=os.environ.get("NEMO_DEFAULT_MODEL") or context_def.default_model, + preferences=prefs, + ) + + +def get_context( + config_path: Path | None = None, + overrides: ConfigParams | None = None, +) -> Context: + """Get the resolved configuration context.""" + config = Config.load(config_path=config_path, overrides=overrides) + return config.resolve() diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/models.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/models.py new file mode 100644 index 00000000000..54dfeed637a --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/config/models.py @@ -0,0 +1,317 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""User-facing configuration models for NemoClient. + +These models represent the ``~/.config/nmp/config.yaml`` file used by the CLI +and SDK to store clusters, users (with auth tokens), and contexts. + +This is distinct from the server-side config in +:mod:`nemo_platform_plugin.config` which reads ``/etc/nmp/config.yaml``. +""" + +from __future__ import annotations + +from abc import ABC +from typing import Annotated, Any, Literal, TypedDict + +from pydantic import ( + BaseModel, + Discriminator, + Field, + HttpUrl, + SecretStr, + SerializationInfo, + Tag, + field_serializer, + field_validator, + model_validator, +) + +DEFAULT_WORKSPACE = "default" +DEFAULT_CONTEXT = "default" +DEFAULT_BASE_URL = "http://localhost:8080" + +# CLI-only type aliases kept as plain strings for config round-tripping. +OutputFormat = Literal["table", "json", "yaml", "markdown", "csv", "raw"] +TimestampFormat = Literal["relative", "iso8601"] + + +class BaseUser(BaseModel, ABC): + def get_client_config(self) -> dict[str, object]: + return {} + + +class OAuthUser(BaseUser): + """User with OAuth token authentication (from device flow, browser flow, etc.).""" + + type: Literal["oauth"] = "oauth" + + name: str = Field(..., min_length=1, description="Unique user name") + token: SecretStr = Field(..., min_length=1, description="Access token (JWT)") + refresh_token: SecretStr | None = Field(default=None, description="Refresh token for automatic renewal") + + @field_validator("name") + @classmethod + def validate_name(cls, v: str) -> str: + if not v or v.isspace(): + raise ValueError("User name cannot be empty") + return v + + @field_serializer("token", "refresh_token", when_used="json") + def serialize_tokens(self, value: SecretStr | None, info: SerializationInfo) -> str | None: + if value is None: + return None + if info.context and info.context.get("include_secrets"): + return value.get_secret_value() + return "***REDACTED***" + + def get_client_config(self) -> dict[str, object]: + return { + "default_headers": { + "Authorization": f"Bearer {self.token.get_secret_value()}", + } + } + + +class NoAuthUser(BaseUser): + """User with no authentication.""" + + type: Literal["no-auth"] = "no-auth" + + name: str = Field(..., min_length=1, description="Unique user name") + + @field_validator("name") + @classmethod + def validate_name(cls, v: str) -> str: + if not v or v.isspace(): + raise ValueError("User name cannot be empty") + return v + + +def _get_user_type(data: Any) -> str: + default = "no-auth" + if isinstance(data, dict): + return data.get("type", default) + return getattr(data, "type", default) + + +User = Annotated[ + Annotated[OAuthUser, Tag("oauth")] | Annotated[NoAuthUser, Tag("no-auth")], + Discriminator(_get_user_type), +] + + +class Cluster(BaseModel): + """Cluster configuration — connection info only.""" + + name: str = Field(..., min_length=1, description="Unique cluster name") + base_url: HttpUrl = Field(..., description="Base URL for the cluster") + metadata: dict[str, Any] = Field(default_factory=dict, description="Additional cluster metadata") + + @field_validator("name") + @classmethod + def validate_name(cls, v: str) -> str: + if not v or v.isspace(): + raise ValueError("Cluster name cannot be empty") + if not v.replace("-", "").replace("_", "").isalnum(): + raise ValueError("Cluster name must be alphanumeric (hyphens and underscores allowed)") + return v + + +class Preferences(BaseModel): + """User preferences for CLI/SDK behavior — can be overridden at runtime.""" + + output_format: OutputFormat = Field(default="table", description="Default output format") + timestamp_format: TimestampFormat = Field(default="iso8601", description="Timestamp display format") + truncate: bool = Field(default=True, description="Truncate long strings in output") + color_output: bool = Field(default=True, description="Enable colored output") + + +class ContextDefinition(BaseModel): + """Context definition from the config file (serialization model). + + Contains string references to cluster and user names that must be + resolved at runtime via :meth:`Config.resolve`. + """ + + name: str = Field(..., min_length=1, description="Unique context name") + cluster: str = Field(..., min_length=1, description="Reference to cluster name") + user: str = Field(..., min_length=1, description="Reference to user name") + workspace: str | None = Field(default=None, description="Default workspace") + default_model: str | None = Field(default=None, description="Default model entity ID for inference") + preferences: Preferences = Field(default_factory=Preferences, description="Context-specific preferences") + metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context metadata") + + @field_validator("name", "cluster", "user") + @classmethod + def validate_identifier(cls, v: str) -> str: + if not v or v.isspace(): + raise ValueError("Identifier cannot be empty") + return v + + +class ConfigParams(TypedDict, total=False): + """Type-safe configuration parameters for overrides.""" + + current_context: str + base_url: str + access_token: str | None + refresh_token: str | None + workspace: str + default_model: str + output_format: OutputFormat + timestamp_format: TimestampFormat + truncate: bool + color_output: bool + + +class LocalServicesConfig(BaseModel): + """User-selected paths for ``nemo services run`` local state.""" + + data_dir: str | None = Field(default=None, description="Directory for local service state") + + +class ConfigFile(BaseModel): + """Root configuration from the YAML config file.""" + + current_context: str | None = Field(default=None, description="Name of the currently active context") + clusters: list[Cluster] = Field(default_factory=list, description="List of configured clusters") + users: list[User] = Field(default_factory=list, description="List of configured users") + contexts: list[ContextDefinition] = Field(default_factory=list, description="List of context definitions") + local_services: LocalServicesConfig | None = Field(default=None, description="Local services config") + + def ensure_context( + self, + context_name: str, + params: ConfigParams, + ) -> tuple[Cluster, User, ContextDefinition]: + """Find or create cluster/user/context entities with the given name.""" + existing_context = next((c for c in self.contexts if c.name == context_name), None) + + cluster_name = existing_context.cluster if existing_context else f"{context_name}-cluster" + user_name = existing_context.user if existing_context else f"{context_name}-user" + + # Find existing or create cluster + cluster = next((c for c in self.clusters if c.name == cluster_name), None) + if cluster is None: + base_url = params.get("base_url") + if not base_url: + raise ValueError(f"Cluster '{cluster_name}' does not exist and no base_url provided to create it!") + cluster = Cluster(name=cluster_name, base_url=HttpUrl(base_url)) + self.clusters.append(cluster) + elif "base_url" in params: + cluster.base_url = HttpUrl(params["base_url"]) + + # Find existing or create user + user: User = next((u for u in self.users if u.name == user_name), None) # type: ignore[assignment] + access_token_provided = "access_token" in params + refresh_token_provided = "refresh_token" in params + access_token = params.get("access_token") + refresh_token = params.get("refresh_token") + + if user is None: + if access_token: + user = OAuthUser( + name=user_name, + token=SecretStr(access_token), + refresh_token=SecretStr(refresh_token) if refresh_token else None, + ) + else: + user = NoAuthUser(name=user_name) + self.users.append(user) + elif access_token_provided: + idx = next(i for i, u in enumerate(self.users) if u.name == user_name) + if access_token: + user = OAuthUser( + name=user_name, + token=SecretStr(access_token), + refresh_token=SecretStr(refresh_token) if refresh_token else None, + ) + else: + user = NoAuthUser(name=user_name) + self.users[idx] = user + elif isinstance(user, OAuthUser) and refresh_token_provided: + idx = next(i for i, u in enumerate(self.users) if u.name == user_name) + user = OAuthUser( + name=user_name, + token=user.token, + refresh_token=SecretStr(refresh_token) if refresh_token else None, + ) + self.users[idx] = user + + # Find existing or create context + context = existing_context + if context is None: + context = ContextDefinition( + name=context_name, + cluster=cluster_name, + user=user_name, + workspace=params.get("workspace", DEFAULT_WORKSPACE), + preferences=Preferences(), + ) + self.contexts.append(context) + + # Apply context-level params + if "workspace" in params: + context.workspace = params["workspace"] + if "default_model" in params: + context.default_model = params["default_model"] + if "output_format" in params: + context.preferences.output_format = params["output_format"] + if "timestamp_format" in params: + context.preferences.timestamp_format = params["timestamp_format"] + if "truncate" in params: + context.preferences.truncate = params["truncate"] + if "color_output" in params: + context.preferences.color_output = params["color_output"] + + return cluster, user, context + + @model_validator(mode="after") + def validate_references(self) -> ConfigFile: + cluster_names = {cluster.name for cluster in self.clusters} + user_names = {user.name for user in self.users} + context_names = {context.name for context in self.contexts} + + for context in self.contexts: + if context.cluster not in cluster_names: + raise ValueError(f"Context '{context.name}' references non-existent cluster '{context.cluster}'") + if context.user not in user_names: + raise ValueError(f"Context '{context.name}' references non-existent user '{context.user}'") + + if self.current_context and self.contexts and self.current_context not in context_names: + raise ValueError(f"Current context '{self.current_context}' does not exist") + + return self + + @model_validator(mode="after") + def validate_unique_names(self) -> ConfigFile: + cluster_names = [cluster.name for cluster in self.clusters] + if len(cluster_names) != len(set(cluster_names)): + raise ValueError("Cluster names must be unique") + + user_names = [user.name for user in self.users] + if len(user_names) != len(set(user_names)): + raise ValueError("User names must be unique") + + context_names = [context.name for context in self.contexts] + if len(context_names) != len(set(context_names)): + raise ValueError("Context names must be unique") + + return self + + +class Context(BaseModel): + """Resolved runtime configuration (what application code should use). + + Unlike :class:`ContextDefinition` (a serialization model from the config file), + this contains fully resolved objects ready for immediate use. + """ + + context_name: str = Field(..., description="Active context name") + cluster: Cluster = Field(..., description="Fully resolved cluster configuration") + user: User | None = Field(default=None, description="Resolved user with authentication credentials") + workspace: str = Field(..., description="Active workspace") + default_model: str | None = Field(default=None, description="Default model entity ID for inference") + preferences: Preferences = Field(..., description="Effective preferences") diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc.py new file mode 100644 index 00000000000..8e466e3df66 --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc.py @@ -0,0 +1,428 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""OIDC token management for NemoClient. + +Provides: + +- :class:`OIDCTokenProvider` — thread-safe OIDC token refresh. +- :class:`TokenSet` — access + refresh token pair with expiry. +- :class:`NMPOIDCConfig` — OIDC discovery response model. +- JWT decode helpers (no verification — for expiry extraction only). +- OIDC discovery and scope helpers. +""" + +from __future__ import annotations + +import asyncio +import base64 +import json +import logging +import threading +import time +from collections.abc import Callable +from contextlib import AbstractContextManager, nullcontext +from dataclasses import dataclass, field +from typing import Any +from urllib.parse import urlparse + +import httpx + +logger = logging.getLogger(__name__) + + +class TokenRefreshError(RuntimeError): + """Structured error raised for OAuth refresh_token grant failures.""" + + def __init__(self, *, error: str, error_description: str) -> None: + self.error = error + self.error_description = error_description + super().__init__(f"Token refresh failed: {error} - {error_description}") + + +# --------------------------------------------------------------------------- +# JWT helpers (decode only, no verification) +# --------------------------------------------------------------------------- + + +def _decode_jwt_segment(token: str, index: int) -> dict[str, Any]: + try: + parts = token.split(".") + if len(parts) != 3: + return {} + payload = parts[index] + payload += "=" * (-len(payload) % 4) + decoded = base64.urlsafe_b64decode(payload) + data = json.loads(decoded) + return data if isinstance(data, dict) else {} + except Exception: + return {} + + +def decode_jwt_claims(token: str) -> dict[str, Any]: + """Decode JWT claims without verification (for display/expiry extraction only).""" + return _decode_jwt_segment(token, 1) + + +def decode_jwt_header(token: str) -> dict[str, Any]: + """Decode JWT header without verification.""" + return _decode_jwt_segment(token, 0) + + +def _base64url_encode_json(payload: dict[str, Any]) -> str: + encoded = json.dumps(payload, separators=(",", ":")).encode("utf-8") + return base64.urlsafe_b64encode(encoded).rstrip(b"=").decode("ascii") + + +def generate_unsigned_jwt( + principal_id: str, + *, + email: str | None = None, + groups: list[str] | None = None, + scopes: list[str] | None = None, + expires_in_seconds: int | None = 3600, + issued_at: int | None = None, + audience: str | None = None, + issuer: str | None = None, + extra_claims: dict[str, Any] | None = None, +) -> str: + """Generate an unsigned JWT (``alg=none``) for local development and testing.""" + now = issued_at if issued_at is not None else int(time.time()) + claims: dict[str, Any] = { + "sub": principal_id, + "iat": now, + } + + if email: + claims["email"] = email + if groups: + claims["groups"] = groups + if scopes: + claims["scope"] = " ".join(scopes) + if expires_in_seconds is not None: + claims["exp"] = now + expires_in_seconds + if audience: + claims["aud"] = audience + if issuer: + claims["iss"] = issuer + if extra_claims: + claims.update(extra_claims) + + header_segment = _base64url_encode_json({"alg": "none", "typ": "JWT"}) + claims_segment = _base64url_encode_json(claims) + return f"{header_segment}.{claims_segment}." + + +# --------------------------------------------------------------------------- +# OIDC discovery +# --------------------------------------------------------------------------- + +DEFAULT_OAUTH_SCOPES = "openid profile email offline_access" + + +@dataclass(frozen=True) +class NMPOIDCConfig: + """OIDC configuration discovered from the NeMo Platform.""" + + auth_enabled: bool + issuer: str | None = None + client_id: str | None = None + token_endpoint: str | None = None + device_authorization_endpoint: str | None = None + default_scopes: str = DEFAULT_OAUTH_SCOPES + scope_prefix: str | None = None + + +def discover_nmp_config(base_url: str, timeout: float = 10.0) -> NMPOIDCConfig: + """Fetch OIDC configuration from the NeMo Platform auth discovery endpoint.""" + response = httpx.get( + f"{base_url.rstrip('/')}/apis/auth/discovery", + timeout=timeout, + ) + response.raise_for_status() + data = response.json() + + oidc = data.get("oidc") or {} + return NMPOIDCConfig( + auth_enabled=data.get("auth_enabled", False), + issuer=oidc.get("issuer"), + client_id=oidc.get("client_id"), + token_endpoint=oidc.get("token_endpoint"), + device_authorization_endpoint=oidc.get("device_authorization_endpoint"), + default_scopes=oidc.get("default_scopes", DEFAULT_OAUTH_SCOPES), + scope_prefix=oidc.get("scope_prefix"), + ) + + +def _discover_oidc_client_settings(base_url: str) -> NMPOIDCConfig: + """Fetch OIDC config with a safe fallback if unreachable.""" + try: + return discover_nmp_config(base_url) + except Exception: + logger.debug("Could not discover OIDC settings from %s", base_url, exc_info=True) + return NMPOIDCConfig( + auth_enabled=False, + client_id="", + token_endpoint="", + default_scopes="openid profile email", + scope_prefix=None, + ) + + +def _normalize_scope_prefix(prefix: str | None) -> str: + if not prefix: + return "" + return prefix if prefix.endswith("/") else f"{prefix}/" + + +def build_effective_scope(requested_scopes: str, scope_prefix: str | None) -> str: + """Prepend scope_prefix to custom scopes (those with ':' or ending with '.default').""" + prefix = _normalize_scope_prefix(scope_prefix) + if not prefix: + return requested_scopes + expanded = [] + for s in requested_scopes.split(): + if ":" in s or s.endswith(".default"): + expanded.append(f"{prefix}{s}") + else: + expanded.append(s) + return " ".join(expanded) + + +# --------------------------------------------------------------------------- +# OAuth refresh_token grant +# --------------------------------------------------------------------------- + +# Refresh proactively when less than this many seconds remain before expiry. +DEFAULT_REFRESH_MARGIN_SECONDS = 60 + + +def _validate_token_endpoint(token_endpoint: str) -> None: + """Reject non-HTTPS token endpoints (except loopback for local dev).""" + parsed = urlparse(token_endpoint) + if parsed.scheme == "https": + return + if parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}: + return + raise ValueError( + f"OIDC token endpoint must use HTTPS (got {token_endpoint!r}). " + "HTTP is only allowed for loopback addresses (localhost, 127.0.0.1, ::1)." + ) + + +def refresh_token_grant( + token_endpoint: str, + client_id: str, + refresh_token: str, + *, + scope: str | None = None, + timeout: float = 30.0, +) -> dict[str, Any]: + """Execute OAuth refresh_token grant and return token response JSON.""" + _validate_token_endpoint(token_endpoint) + data: dict[str, str] = { + "grant_type": "refresh_token", + "client_id": client_id, + "refresh_token": refresh_token, + } + if scope: + data["scope"] = scope + + response = httpx.post(token_endpoint, data=data, timeout=timeout) + + if response.status_code != 200: + error_data: dict[str, str] = {} + if response.headers.get("content-type", "").startswith("application/json"): + try: + error_data = response.json() + except (json.JSONDecodeError, ValueError): + error_data = {} + error = error_data.get("error", "unknown_error") + error_description = error_data.get("error_description", response.text) + raise TokenRefreshError(error=error, error_description=error_description) + + return response.json() + + +# --------------------------------------------------------------------------- +# TokenSet +# --------------------------------------------------------------------------- + + +@dataclass +class TokenSet: + """A pair of access + refresh tokens with expiry metadata.""" + + access_token: str = field(repr=False) + refresh_token: str | None = field(default=None, repr=False) + expires_at: float | None = None + + @staticmethod + def from_access_token( + access_token: str, + refresh_token: str | None = None, + *, + expires_in: int | float | None = None, + ) -> TokenSet: + """Create a TokenSet, extracting expiry from the JWT's ``exp`` claim. + + Falls back to ``expires_in`` (seconds from now) for opaque tokens + that don't contain a JWT ``exp`` claim. + """ + expires_at = None + claims = decode_jwt_claims(access_token) + if claims: + expires_at = claims.get("exp") + if expires_at is None and expires_in is not None: + expires_at = time.time() + float(expires_in) + return TokenSet( + access_token=access_token, + refresh_token=refresh_token, + expires_at=float(expires_at) if expires_at is not None else None, + ) + + def is_expired(self, margin_seconds: float = DEFAULT_REFRESH_MARGIN_SECONDS) -> bool: + """Check if the access token is expired or about to expire.""" + if self.expires_at is None: + return False + return time.time() >= (self.expires_at - margin_seconds) + + +# --------------------------------------------------------------------------- +# OIDCTokenProvider +# --------------------------------------------------------------------------- + + +@dataclass +class OIDCTokenProvider: + """Provides access tokens with automatic refresh via the OAuth2 refresh_token grant. + + This is the core component for SDK-level token management. It: + - Holds the current access + refresh tokens + - Proactively refreshes the access token before it expires + - Is thread-safe (uses a lock for concurrent access) + - Optionally persists refreshed tokens via a callback + """ + + token_endpoint: str + client_id: str + tokens: TokenSet = field(default_factory=lambda: TokenSet(access_token=""), repr=False) + refresh_margin_seconds: float = DEFAULT_REFRESH_MARGIN_SECONDS + refresh_scope: str | None = None + load_tokens: Callable[[], TokenSet | None] | None = None + refresh_lock: Callable[[], AbstractContextManager[None]] | None = None + on_tokens_refreshed: Callable[[TokenSet], None] | None = None + _lock: threading.Lock = field(default_factory=threading.Lock, repr=False) + + def get_access_token(self) -> str: + """Return a valid access token, refreshing if necessary.""" + with self._lock: + if self.tokens.is_expired(self.refresh_margin_seconds): + self._refresh() + return self.tokens.access_token + + async def get_access_token_async(self) -> str: + """Return a valid access token in async contexts. + + Runs refresh logic in a worker thread so token refresh does not block the + event loop. + """ + return await asyncio.to_thread(self.get_access_token) + + def reload_tokens(self) -> bool: + """Reload tokens from a shared store, if configured.""" + with self._lock: + return self._reload_tokens_from_source() + + def _reload_tokens_from_source(self) -> bool: + if self.load_tokens is None: + return False + + try: + loaded_tokens = self.load_tokens() + except Exception: + logger.warning("Failed to reload shared tokens", exc_info=True) + return False + + if loaded_tokens is None or loaded_tokens == self.tokens: + return False + + self.tokens = loaded_tokens + logger.debug("Reloaded shared tokens (expires_at=%s)", self.tokens.expires_at) + return True + + def _refresh(self, *, force: bool = False) -> None: + """Refresh the access token using the refresh_token grant.""" + lock_context = self.refresh_lock() if self.refresh_lock is not None else nullcontext() + with lock_context: + self._reload_tokens_from_source() + if not force and not self.tokens.is_expired(self.refresh_margin_seconds): + return + + if not self.tokens.refresh_token: + raise RuntimeError( + "Access token has expired and no refresh token is available. " + "Re-authenticate with `nemo auth login` to obtain new tokens." + ) + + logger.debug("Refreshing access token via %s", self.token_endpoint) + + token_data: dict + try: + token_data = refresh_token_grant( + token_endpoint=self.token_endpoint, + client_id=self.client_id, + refresh_token=self.tokens.refresh_token, + scope=self.refresh_scope, + ) + except TokenRefreshError as exc: + if exc.error != "invalid_grant": + raise + + if not self._reload_tokens_from_source(): + raise + + if not force and not self.tokens.is_expired(self.refresh_margin_seconds): + logger.debug("Recovered from invalid_grant with shared tokens") + return + + if not self.tokens.refresh_token: + raise RuntimeError( + "Access token has expired and no refresh token is available. " + "Re-authenticate with `nemo auth login` to obtain new tokens." + ) + + token_data = refresh_token_grant( + token_endpoint=self.token_endpoint, + client_id=self.client_id, + refresh_token=self.tokens.refresh_token, + scope=self.refresh_scope, + ) + + new_access_token = token_data["access_token"] + # The IdP may rotate the refresh token. + old_refresh_token = self.tokens.refresh_token + new_refresh_token = token_data.get("refresh_token", old_refresh_token) + refresh_token_rotated = new_refresh_token != old_refresh_token + + self.tokens = TokenSet.from_access_token( + new_access_token, new_refresh_token, expires_in=token_data.get("expires_in") + ) + logger.debug("Access token refreshed successfully (expires_at=%s)", self.tokens.expires_at) + + if self.on_tokens_refreshed: + try: + self.on_tokens_refreshed(self.tokens) + except Exception: + if refresh_token_rotated: + # The IdP rotated the refresh token but we failed to + # persist it. The old refresh token is now invalid, so + # swallowing this would silently lose the user's session. + raise + logger.warning("Failed to persist refreshed tokens", exc_info=True) + + def force_refresh(self) -> str: + """Force a token refresh regardless of expiry. Returns the new access token.""" + with self._lock: + self._refresh(force=True) + return self.tokens.access_token diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc_factory.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc_factory.py new file mode 100644 index 00000000000..d4244bdc070 --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client/oidc_factory.py @@ -0,0 +1,212 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""OIDC provider factory for NemoClient.from_config(). + +Manages provider caching, config-file token persistence, and cross-process +locking so that multiple ``NemoClient`` instances (and processes) sharing the +same config file coordinate token refreshes correctly. +""" + +from __future__ import annotations + +import logging +import os +import threading +from collections.abc import Callable +from contextlib import AbstractContextManager, contextmanager +from dataclasses import dataclass +from pathlib import Path + +from nemo_platform_plugin.client.auth import AuthError +from nemo_platform_plugin.client.oidc import ( + DEFAULT_REFRESH_MARGIN_SECONDS, + OIDCTokenProvider, + TokenSet, + _discover_oidc_client_settings, + build_effective_scope, +) + +logger = logging.getLogger(__name__) + +# Guards _TOKEN_PROVIDER_CACHE; acquired only during dict lookup/insert (fast). +_TOKEN_PROVIDER_CACHE_LOCK = threading.Lock() + + +@dataclass(frozen=True) +class _ProviderCacheKey: + """Composite key for the provider cache.""" + + config_path: Path + context_name: str + token_endpoint: str + client_id: str + refresh_scope: str | None + + +# Process-wide cache: (config_path, context) → shared OIDCTokenProvider. +_TOKEN_PROVIDER_CACHE: dict[_ProviderCacheKey, OIDCTokenProvider] = {} + + +def _make_config_persister(context_name: str, config_path: Path | None = None) -> Callable[[TokenSet], None]: + """Create an ``on_tokens_refreshed`` callback that writes new tokens to the config file.""" + + def persist(tokens: TokenSet) -> None: + from nemo_platform_plugin.client.config.config import Config + from nemo_platform_plugin.client.config.models import ConfigParams + + params: ConfigParams = {"access_token": tokens.access_token} + if tokens.refresh_token: + params["refresh_token"] = tokens.refresh_token + Config.write(params, context_name=context_name, config_path=config_path) + logger.debug("Persisted refreshed tokens to nmp config (context=%s)", context_name) + + return persist + + +def _make_config_token_loader(context_name: str, config_path: Path) -> Callable[[], TokenSet | None]: + """Create a ``load_tokens`` callback that re-reads tokens from the config file.""" + + def load_tokens() -> TokenSet | None: + from nemo_platform_plugin.client.config.config import Config + from nemo_platform_plugin.client.config.models import ConfigParams, OAuthUser + + overrides: ConfigParams = {"current_context": context_name} + try: + config = Config.load(config_path=config_path, overrides=overrides) + resolved = config.resolve() + except Exception: + logger.debug("Failed to reload tokens from nmp config (context=%s)", context_name, exc_info=True) + return None + + if not isinstance(resolved.user, OAuthUser): + return None + + return TokenSet.from_access_token( + resolved.user.token.get_secret_value(), + resolved.user.refresh_token.get_secret_value() if resolved.user.refresh_token else None, + ) + + return load_tokens + + +def _build_refresh_lock_path(config_path: Path, context_name: str) -> Path: + safe_context = context_name.replace(os.sep, "_") + if os.altsep: + safe_context = safe_context.replace(os.altsep, "_") + return config_path.with_name(f"{config_path.name}.{safe_context}.oauth-refresh.lock") + + +def _make_refresh_lock(config_path: Path, context_name: str) -> Callable[[], AbstractContextManager[None]]: + """Create a cross-process file lock for serializing token refreshes.""" + lock_path = _build_refresh_lock_path(config_path, context_name) + + @contextmanager + def refresh_lock(): + try: + import fcntl + except ImportError: + # Windows: no fcntl — skip cross-process locking. + yield + return + + lock_path.parent.mkdir(parents=True, exist_ok=True) + with open(lock_path, "a+", encoding="utf-8") as lock_file: + fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX) + try: + yield + finally: + fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN) + + return refresh_lock + + +def _normalize_config_path(path: Path) -> Path: + return path.expanduser().resolve(strict=False) + + +def _get_or_create_provider( + key: _ProviderCacheKey, + create_provider: Callable[[], OIDCTokenProvider], +) -> OIDCTokenProvider: + """Return the cached provider for *key*, or create and cache a new one.""" + with _TOKEN_PROVIDER_CACHE_LOCK: + provider = _TOKEN_PROVIDER_CACHE.get(key) + if provider is None: + provider = create_provider() + _TOKEN_PROVIDER_CACHE[key] = provider + return provider + + # Provider already existed — reload tokens from disk in case another + # process refreshed them since we last checked. + provider.reload_tokens() + return provider + + +def resolve_oidc_provider( + *, + base_url: str, + context_name: str, + access_token: str, + refresh_token: str | None, + config_exists: bool, + config_path: Path, + explicit_access_token: bool = False, +) -> OIDCTokenProvider: + """Build or retrieve a cached OIDCTokenProvider for a resolved config context. + + This is the bridge between ``NemoClient.from_config()`` and the OIDC machinery. + """ + oidc_config = _discover_oidc_client_settings(base_url) + tokens = TokenSet.from_access_token(access_token, refresh_token) + + token_endpoint = oidc_config.token_endpoint or "" + client_id = oidc_config.client_id or "" + refresh_scope = build_effective_scope(oidc_config.default_scopes, oidc_config.scope_prefix) + + if refresh_token and (not token_endpoint or not client_id): + raise AuthError( + "OIDC discovery did not return token_endpoint/client_id; " + "cannot refresh OAuth tokens. Check cluster auth configuration." + ) + + # Only share the provider (and enable persistence/locking) when reading + # from an actual config file. If the caller passed an explicit + # access_token, they own the token lifecycle. + share_provider = config_exists and not explicit_access_token + + if share_provider: + normalized_config_path = _normalize_config_path(config_path) + provider_key = _ProviderCacheKey( + config_path=normalized_config_path, + context_name=context_name, + token_endpoint=token_endpoint, + client_id=client_id, + refresh_scope=refresh_scope, + ) + on_refreshed = _make_config_persister(context_name, config_path) + load_tokens_cb = _make_config_token_loader(context_name, config_path) + refresh_lock = _make_refresh_lock(config_path, context_name) + + return _get_or_create_provider( + provider_key, + lambda: OIDCTokenProvider( + token_endpoint=token_endpoint, + client_id=client_id, + tokens=tokens, + refresh_margin_seconds=DEFAULT_REFRESH_MARGIN_SECONDS, + refresh_scope=refresh_scope, + load_tokens=load_tokens_cb, + refresh_lock=refresh_lock, + on_tokens_refreshed=on_refreshed, + ), + ) + + # Ephemeral provider: no persistence, no file locking, no caching. + return OIDCTokenProvider( + token_endpoint=token_endpoint, + client_id=client_id, + tokens=tokens, + refresh_margin_seconds=DEFAULT_REFRESH_MARGIN_SECONDS, + refresh_scope=refresh_scope, + ) diff --git a/packages/nemo_platform_plugin/src/nemo_platform_plugin/client_provider.py b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client_provider.py new file mode 100644 index 00000000000..a719dc9ed35 --- /dev/null +++ b/packages/nemo_platform_plugin/src/nemo_platform_plugin/client_provider.py @@ -0,0 +1,108 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""NemoClient factory for task containers and services. + +Builds :class:`~nemo_platform_plugin.client.client.NemoClient` / +:class:`~nemo_platform_plugin.client.client.AsyncNemoClient` from +environment variables (``NMP_BASE_URL``, ``NMP_PRINCIPAL``). + +For user-facing / CLI usage, prefer ``NemoClient.from_config()`` which +reads ``~/.config/nmp/config.yaml`` and wires up OIDC token refresh. +""" + +from __future__ import annotations + +import json +import logging +import os +from typing import Any + +from nemo_platform_plugin.client.client import AsyncNemoClient, NemoClient + +logger = logging.getLogger(__name__) + +_INTERNAL_REQUEST_HEADER = "X-NMP-Internal" +_NMP_PRINCIPAL_ENVVAR = "NMP_PRINCIPAL" + + +def _read_principal_from_env() -> dict[str, Any] | None: + raw = os.environ.get(_NMP_PRINCIPAL_ENVVAR) + if not raw: + return None + try: + data = json.loads(raw) + except json.JSONDecodeError as exc: + raise ValueError(f"Invalid JSON in {_NMP_PRINCIPAL_ENVVAR}: {exc}") from exc + if not isinstance(data, dict) or not data.get("id"): + return None + return data + + +def _build_headers( + *, + as_service: str | None = None, + internal: bool = False, + on_behalf_of: str | None = None, +) -> dict[str, str]: + """Build X-NMP-* headers from env vars and explicit parameters.""" + headers: dict[str, str] = {} + + if internal: + headers[_INTERNAL_REQUEST_HEADER] = "true" + + if as_service is not None: + headers["X-NMP-Principal-Id"] = f"service:{as_service}" + else: + principal = _read_principal_from_env() + if principal is not None: + headers["X-NMP-Principal-Id"] = principal["id"] + if principal.get("email"): + headers["X-NMP-Principal-Email"] = principal["email"] + if principal.get("groups"): + headers["X-NMP-Principal-Groups"] = ",".join(principal["groups"]) + if principal.get("on_behalf_of"): + headers["X-NMP-Principal-On-Behalf-Of"] = principal["on_behalf_of"] + if principal.get("on_behalf_of_email"): + headers["X-NMP-Principal-On-Behalf-Of-Email"] = principal["on_behalf_of_email"] + if principal.get("on_behalf_of_groups"): + headers["X-NMP-Principal-On-Behalf-Of-Groups"] = ",".join(principal["on_behalf_of_groups"]) + + if on_behalf_of is not None: + headers["X-NMP-Principal-On-Behalf-Of"] = on_behalf_of + + return headers + + +def _base_url() -> str: + return os.environ.get("NMP_BASE_URL", "http://localhost:8080") + + +def get_nemo_client( + *, + as_service: str | None = None, + internal: bool = False, + on_behalf_of: str | None = None, +) -> NemoClient: + """Build a sync NemoClient for the current service context. + + Reads ``NMP_BASE_URL`` (default ``http://localhost:8080``) and + ``NMP_PRINCIPAL`` from the environment. + """ + headers = _build_headers(as_service=as_service, internal=internal, on_behalf_of=on_behalf_of) + return NemoClient(base_url=_base_url(), default_headers=headers or None) + + +def get_async_nemo_client( + *, + as_service: str | None = None, + internal: bool = False, + on_behalf_of: str | None = None, +) -> AsyncNemoClient: + """Build an async NemoClient for the current service context. + + Reads ``NMP_BASE_URL`` (default ``http://localhost:8080``) and + ``NMP_PRINCIPAL`` from the environment. + """ + headers = _build_headers(as_service=as_service, internal=internal, on_behalf_of=on_behalf_of) + return AsyncNemoClient(base_url=_base_url(), default_headers=headers or None) diff --git a/packages/nemo_platform_plugin/tests/test_client_auth.py b/packages/nemo_platform_plugin/tests/test_client_auth.py new file mode 100644 index 00000000000..5ad150ad399 --- /dev/null +++ b/packages/nemo_platform_plugin/tests/test_client_auth.py @@ -0,0 +1,489 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Tests for NemoClient first-class auth support (AIRCORE-828).""" + +from __future__ import annotations + +import asyncio +import time +from unittest.mock import patch + +import httpx +import pytest +import respx +import yaml +from nemo_platform_plugin.client.auth import ( + StaticToken, + TokenProvider, +) +from nemo_platform_plugin.client.client import AsyncNemoClient, NemoClient +from nemo_platform_plugin.client.config.config import Config +from nemo_platform_plugin.client.config.models import ( + NoAuthUser, + OAuthUser, +) +from nemo_platform_plugin.client.oidc import ( + OIDCTokenProvider, + TokenSet, + generate_unsigned_jwt, +) +from nemo_platform_plugin.client_provider import ( + get_async_nemo_client, + get_nemo_client, +) + +# --------------------------------------------------------------------------- +# StaticToken +# --------------------------------------------------------------------------- + + +class TestStaticToken: + def test_get_access_token(self): + provider = StaticToken("my-token") + assert provider.get_access_token() == "my-token" + + def test_satisfies_protocol(self): + provider = StaticToken("t") + assert isinstance(provider, TokenProvider) + + def test_async_get_access_token(self): + provider = StaticToken("my-token") + result = asyncio.run(provider.get_access_token_async()) + assert result == "my-token" + + +# --------------------------------------------------------------------------- +# NemoClient auth parameter +# --------------------------------------------------------------------------- + + +class TestNemoClientAuth: + @respx.mock + def test_string_auth_sets_bearer_header(self): + """NemoClient(auth='token') sets Authorization header on requests.""" + route = respx.get("http://localhost:8080/test").mock(return_value=httpx.Response(200, json={"ok": True})) + client = NemoClient(base_url="http://localhost:8080", auth="my-secret-token") + + from nemo_platform_plugin.client.types import PreparedRequest + + req = PreparedRequest( + method="GET", path_template="/test", path_params={}, content=None, content_type=None, response_type=None + ) + client.send(req) + + assert route.called + assert route.calls[0].request.headers["Authorization"] == "Bearer my-secret-token" + + @respx.mock + def test_custom_provider_called_per_request(self): + """NemoClient(auth=CustomProvider()) calls get_access_token() per request.""" + route = respx.get("http://localhost:8080/test").mock(return_value=httpx.Response(200, json={"ok": True})) + + call_count = 0 + + class CountingProvider: + def get_access_token(self) -> str: + nonlocal call_count + call_count += 1 + return f"token-{call_count}" + + client = NemoClient(base_url="http://localhost:8080", auth=CountingProvider()) + + from nemo_platform_plugin.client.types import PreparedRequest + + req = PreparedRequest( + method="GET", path_template="/test", path_params={}, content=None, content_type=None, response_type=None + ) + client.send(req) + client.send(req) + + assert route.calls[0].request.headers["Authorization"] == "Bearer token-1" + assert route.calls[1].request.headers["Authorization"] == "Bearer token-2" + assert call_count == 2 + + @respx.mock + def test_no_auth_no_header(self): + """NemoClient without auth does not add Authorization header.""" + route = respx.get("http://localhost:8080/test").mock(return_value=httpx.Response(200, json={"ok": True})) + client = NemoClient(base_url="http://localhost:8080") + + from nemo_platform_plugin.client.types import PreparedRequest + + req = PreparedRequest( + method="GET", path_template="/test", path_params={}, content=None, content_type=None, response_type=None + ) + client.send(req) + + assert route.called + assert "Authorization" not in route.calls[0].request.headers + + +# --------------------------------------------------------------------------- +# AsyncNemoClient auth parameter +# --------------------------------------------------------------------------- + + +class TestAsyncNemoClientAuth: + @respx.mock + def test_async_provider_called(self): + """AsyncNemoClient(auth=AsyncProvider()) calls async get_access_token().""" + route = respx.get("http://localhost:8080/test").mock(return_value=httpx.Response(200, json={"ok": True})) + + class AsyncProvider: + async def get_access_token(self) -> str: + return "async-token" + + client = AsyncNemoClient(base_url="http://localhost:8080", auth=AsyncProvider()) + + from nemo_platform_plugin.client.types import PreparedRequest + + req = PreparedRequest( + method="GET", path_template="/test", path_params={}, content=None, content_type=None, response_type=None + ) + + asyncio.run(client.send(req)) + + assert route.called + assert route.calls[0].request.headers["Authorization"] == "Bearer async-token" + + @respx.mock + def test_sync_provider_works_in_async_client(self): + """AsyncNemoClient accepts a sync TokenProvider too.""" + route = respx.get("http://localhost:8080/test").mock(return_value=httpx.Response(200, json={"ok": True})) + client = AsyncNemoClient(base_url="http://localhost:8080", auth="sync-token") + + from nemo_platform_plugin.client.types import PreparedRequest + + req = PreparedRequest( + method="GET", path_template="/test", path_params={}, content=None, content_type=None, response_type=None + ) + + asyncio.run(client.send(req)) + + assert route.called + assert route.calls[0].request.headers["Authorization"] == "Bearer sync-token" + + +# --------------------------------------------------------------------------- +# OIDCTokenProvider +# --------------------------------------------------------------------------- + + +def _make_jwt(exp: float | None = None, sub: str = "user") -> str: + """Create a minimal unsigned JWT for testing.""" + return generate_unsigned_jwt( + principal_id=sub, + expires_in_seconds=int(exp - time.time()) if exp else 3600, + ) + + +class TestOIDCTokenProvider: + def test_returns_token_when_not_expired(self): + token = _make_jwt(exp=time.time() + 3600) + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet.from_access_token(token), + ) + assert provider.get_access_token() == token + + def test_refreshes_when_expired(self): + expired_token = _make_jwt(exp=time.time() - 100) + new_token = _make_jwt(exp=time.time() + 3600) + + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet(access_token=expired_token, refresh_token="refresh-me", expires_at=time.time() - 100), + ) + + with patch("nemo_platform_plugin.client.oidc.refresh_token_grant") as mock_grant: + mock_grant.return_value = {"access_token": new_token} + result = provider.get_access_token() + + assert result == new_token + mock_grant.assert_called_once() + + def test_persists_rotated_tokens(self): + expired_token = _make_jwt(exp=time.time() - 100) + new_token = _make_jwt(exp=time.time() + 3600) + persisted = [] + + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet(access_token=expired_token, refresh_token="old-refresh", expires_at=time.time() - 100), + on_tokens_refreshed=lambda ts: persisted.append(ts), + ) + + with patch("nemo_platform_plugin.client.oidc.refresh_token_grant") as mock_grant: + mock_grant.return_value = {"access_token": new_token, "refresh_token": "new-refresh"} + provider.get_access_token() + + assert len(persisted) == 1 + assert persisted[0].access_token == new_token + assert persisted[0].refresh_token == "new-refresh" + + def test_raises_when_no_refresh_token(self): + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet(access_token="expired", expires_at=time.time() - 100), + ) + with pytest.raises(RuntimeError, match="no refresh token"): + provider.get_access_token() + + def test_invalid_grant_recovery_with_shared_tokens(self): + """On invalid_grant, reload tokens from shared store and retry.""" + expired_token = _make_jwt(exp=time.time() - 100) + fresh_token = _make_jwt(exp=time.time() + 3600) + + from nemo_platform_plugin.client.oidc import TokenRefreshError + + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet(access_token=expired_token, refresh_token="stale-refresh", expires_at=time.time() - 100), + load_tokens=lambda: TokenSet( + access_token=fresh_token, refresh_token="fresh-refresh", expires_at=time.time() + 3600 + ), + ) + + with patch("nemo_platform_plugin.client.oidc.refresh_token_grant") as mock_grant: + mock_grant.side_effect = TokenRefreshError(error="invalid_grant", error_description="token revoked") + result = provider.get_access_token() + + # Should have recovered by reloading fresh tokens from the shared store + assert result == fresh_token + + +# --------------------------------------------------------------------------- +# Config +# --------------------------------------------------------------------------- + + +class TestConfig: + def test_load_and_resolve(self, tmp_path): + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "oauth", "token": "my-token"}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user", "workspace": "ws1"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + config = Config.load(config_path=config_file) + ctx = config.resolve() + + assert ctx.context_name == "test" + assert str(ctx.cluster.base_url).rstrip("/") == "http://localhost:9090" + assert ctx.workspace == "ws1" + assert isinstance(ctx.user, OAuthUser) + assert ctx.user.token.get_secret_value() == "my-token" + + def test_load_nonexistent_explicit_path_raises(self, tmp_path): + missing = tmp_path / "does-not-exist.yaml" + with pytest.raises(FileNotFoundError): + Config.load(config_path=missing) + + def test_write_then_read_round_trip(self, tmp_path): + config_file = tmp_path / "config.yaml" + Config.write( + {"base_url": "http://localhost:9999", "access_token": "round-trip-token"}, + context_name="rt", + config_path=config_file, + set_current_on_create=True, + ) + + config = Config.load(config_path=config_file) + ctx = config.resolve() + assert ctx.context_name == "rt" + assert str(ctx.cluster.base_url).rstrip("/") == "http://localhost:9999" + assert isinstance(ctx.user, OAuthUser) + assert ctx.user.token.get_secret_value() == "round-trip-token" + + def test_migrate_legacy_api_key_to_oauth(self, tmp_path): + """Legacy api-key users are migrated to oauth on load.""" + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "api-key", "api_key": "my-api-key"}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + config = Config.load(config_path=config_file) + ctx = config.resolve() + assert isinstance(ctx.user, OAuthUser) + assert ctx.user.token.get_secret_value() == "my-api-key" + + def test_migrate_legacy_api_key_empty_becomes_no_auth(self, tmp_path): + """Legacy api-key users with empty keys become no-auth.""" + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "api-key", "api_key": ""}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + config = Config.load(config_path=config_file) + ctx = config.resolve() + assert isinstance(ctx.user, NoAuthUser) + + def test_resolve_no_auth_user(self, tmp_path): + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "no-auth"}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + config = Config.load(config_path=config_file) + ctx = config.resolve() + + assert isinstance(ctx.user, NoAuthUser) + + +# --------------------------------------------------------------------------- +# NemoClient.from_config +# --------------------------------------------------------------------------- + + +class TestFromConfig: + def test_from_config_with_oauth(self, tmp_path): + token = _make_jwt() + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "oauth", "token": token}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + with patch("nemo_platform_plugin.client.oidc._discover_oidc_client_settings") as mock_discover: + from nemo_platform_plugin.client.oidc import NMPOIDCConfig + + mock_discover.return_value = NMPOIDCConfig( + auth_enabled=True, + client_id="test-client", + token_endpoint="https://idp/token", + ) + client = NemoClient.from_config(config_path=config_file) + + assert client.base_url == "http://localhost:9090" + assert client._auth is not None + + def test_from_config_with_no_auth(self, tmp_path): + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "no-auth"}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + client = NemoClient.from_config(config_path=config_file) + assert client.base_url == "http://localhost:9090" + assert client._auth is None + + def test_from_config_selects_context(self, tmp_path): + """from_config(context='staging') uses the staging context, not the default.""" + config_data = { + "current_context": "prod", + "clusters": [ + {"name": "prod-cluster", "base_url": "http://prod:8080"}, + {"name": "staging-cluster", "base_url": "http://staging:9090"}, + ], + "users": [ + {"name": "prod-user", "type": "no-auth"}, + {"name": "staging-user", "type": "no-auth"}, + ], + "contexts": [ + {"name": "prod", "cluster": "prod-cluster", "user": "prod-user"}, + {"name": "staging", "cluster": "staging-cluster", "user": "staging-user"}, + ], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + client = NemoClient.from_config(context="staging", config_path=config_file) + assert client.base_url == "http://staging:9090" + + def test_from_config_nonexistent_path_raises(self, tmp_path): + missing = tmp_path / "nope.yaml" + with pytest.raises(FileNotFoundError): + NemoClient.from_config(config_path=missing) + + def test_async_from_config(self, tmp_path): + config_data = { + "current_context": "test", + "clusters": [{"name": "test-cluster", "base_url": "http://localhost:9090"}], + "users": [{"name": "test-user", "type": "no-auth"}], + "contexts": [{"name": "test", "cluster": "test-cluster", "user": "test-user"}], + } + config_file = tmp_path / "config.yaml" + config_file.write_text(yaml.safe_dump(config_data)) + + client = AsyncNemoClient.from_config(config_path=config_file) + assert isinstance(client, AsyncNemoClient) + assert client.base_url == "http://localhost:9090" + + +# --------------------------------------------------------------------------- +# get_nemo_client / get_async_nemo_client +# --------------------------------------------------------------------------- + + +class TestGetNemoClient: + def test_returns_sync_client(self): + client = get_nemo_client(as_service="test-svc", internal=True) + assert isinstance(client, NemoClient) + + def test_returns_async_client(self): + client = get_async_nemo_client(as_service="test-svc") + assert isinstance(client, AsyncNemoClient) + + +# --------------------------------------------------------------------------- +# Security: token repr and endpoint validation +# --------------------------------------------------------------------------- + + +class TestSecurity: + def test_token_set_repr_hides_tokens(self): + ts = TokenSet(access_token="secret-access", refresh_token="secret-refresh", expires_at=123.0) + r = repr(ts) + assert "secret-access" not in r + assert "secret-refresh" not in r + assert "123.0" in r # expires_at is still visible + + def test_oidc_provider_repr_hides_tokens(self): + provider = OIDCTokenProvider( + token_endpoint="https://idp/token", + client_id="client", + tokens=TokenSet(access_token="secret", expires_at=999.0), + ) + r = repr(provider) + assert "secret" not in r + assert "idp" in r # non-sensitive fields are visible + + def test_refresh_token_grant_rejects_http_endpoint(self): + from nemo_platform_plugin.client.oidc import _validate_token_endpoint + + # HTTPS is fine + _validate_token_endpoint("https://idp.example.com/token") + # HTTP loopback is fine + _validate_token_endpoint("http://localhost:8080/token") + _validate_token_endpoint("http://127.0.0.1:8080/token") + # HTTP non-loopback is rejected + with pytest.raises(ValueError, match="HTTPS"): + _validate_token_endpoint("http://evil.example.com/token")