stackport 0.2.6__tar.gz → 0.3.0__tar.gz

{stackport-0.2.6/stackport.egg-info → stackport-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackport
-Version: 0.2.6
+Version: 0.3.0
 Summary: Universal AWS resource browser for local emulators
 Author: Davi Reis Vieira
 License: MIT
@@ -68,6 +68,7 @@ Dynamic: license-file
 - **8 dedicated service UIs** for S3, DynamoDB, Lambda, SQS, IAM, EC2, CloudWatch Logs, and Secrets Manager
 - **Write operations** — upload/delete S3 objects, query DynamoDB, invoke Lambda, send/receive SQS messages
 - **Real AWS support** — connect to real AWS accounts with read-only mode by default
+- **Per-endpoint authentication** — default credentials, AWS profiles (SSO/AssumeRole), or static keys per endpoint
 - **Tag management** — unified tagging across 21 resource types
 - **CLI** — `stackport status`, `list`, `describe`, `export` with JSON/CSV/table output
 - **Real-time dashboard** with WebSocket-powered live updates
@@ -101,6 +102,8 @@ AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-west-2 stackpo
 STACKPORT_ALLOW_WRITES=false AWS_PROFILE=my-profile stackport
 ```
 
+You can also configure per-endpoint authentication from the Settings UI — select a profile, enter static credentials, or use the default credential chain per endpoint. See [Per-endpoint authentication](#per-endpoint-authentication) below.
+
 When connected to real AWS, StackPort shows a warning banner and operates in read-only mode unless writes are explicitly enabled.
 
 ### Docker Compose (MiniStack + StackPort)
@@ -159,6 +162,30 @@ See [`examples/docker-compose.multi-endpoint.yml`](examples/docker-compose.multi
 
 The endpoint selector appears in the sidebar when more than one endpoint is configured. Each endpoint is health-checked independently, and all API requests, caches, and WebSocket subscriptions are scoped to the active endpoint.
 
+### Per-endpoint authentication
+
+Each endpoint can use its own AWS authentication method, configured from the Settings UI:
+
+| Auth Type | Description | Use Case |
+|-----------|-------------|----------|
+| **Default** | Uses `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` env vars or instance role | Local emulators, EC2/ECS deployments |
+| **AWS Profile** | Uses a named profile from `~/.aws/config` | SSO, AssumeRole, multiple accounts |
+| **Static Credentials** | Per-endpoint access key and secret | Service accounts, cross-account access |
+
+**Profile auth** supports SSO, AssumeRole, and credential_process — anything `boto3.Session(profile_name=...)` handles. If your SSO token expires, StackPort returns a 401 with instructions to run `aws sso login --profile <name>`.
+
+**Docker users:** mount your AWS config to use profiles inside the container:
+
+```yaml
+services:
+  stackport:
+    image: davireis/stackport
+    volumes:
+      - ~/.aws:/root/.aws
+```
+
+You can test connections before saving using the "Test Connection" button in the add/edit endpoint dialog.
+
 ## Service Browsers
 
 ### Dedicated UIs (8 services)
@@ -240,6 +267,7 @@ Press `?` anywhere to see all shortcuts.
 | `STACKPORT_CACHE_TTL` | `5` | Seconds to cache service stats |
 | `STACKPORT_PROBE_WORKERS` | `10` | Max concurrent workers for service probing |
 | `STACKPORT_ENDPOINTS` | *(unset)* | Multiple endpoints: `local=http://localhost:4566,staging=http://...` |
+| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json) |
 | `LOG_LEVEL` | `INFO` | Python log level (`DEBUG` shows healthcheck logs) |
 
 ## Supported Services (35)
@@ -263,8 +291,8 @@ cd ui && npm install && npm run dev
 cd ui && npm run build
 
 # Run tests
-python -m pytest tests/ -x --tb=short    # backend (262 tests)
-cd ui && npx vitest run                   # frontend (163 tests)
+python -m pytest tests/ -x --tb=short    # backend (362 tests)
+cd ui && npx vitest run                   # frontend (176 tests)
 
 # Typecheck & lint
 cd ui && npx tsc -b
@@ -285,6 +313,7 @@ backend/
   routes/
     stats.py       Service discovery with concurrent probing
     resources.py   Generic list/detail for all services
+    endpoints.py   Endpoint CRUD, health checks, profile listing
     tags.py        Unified tag management (21 types)
     s3.py          S3 file browser with write ops
     dynamodb.py    DynamoDB query/scan

{stackport-0.2.6 → stackport-0.3.0}/README.md

@@ -33,6 +33,7 @@
 - **8 dedicated service UIs** for S3, DynamoDB, Lambda, SQS, IAM, EC2, CloudWatch Logs, and Secrets Manager
 - **Write operations** — upload/delete S3 objects, query DynamoDB, invoke Lambda, send/receive SQS messages
 - **Real AWS support** — connect to real AWS accounts with read-only mode by default
+- **Per-endpoint authentication** — default credentials, AWS profiles (SSO/AssumeRole), or static keys per endpoint
 - **Tag management** — unified tagging across 21 resource types
 - **CLI** — `stackport status`, `list`, `describe`, `export` with JSON/CSV/table output
 - **Real-time dashboard** with WebSocket-powered live updates
@@ -66,6 +67,8 @@ AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-west-2 stackpo
 STACKPORT_ALLOW_WRITES=false AWS_PROFILE=my-profile stackport
 ```
 
+You can also configure per-endpoint authentication from the Settings UI — select a profile, enter static credentials, or use the default credential chain per endpoint. See [Per-endpoint authentication](#per-endpoint-authentication) below.
+
 When connected to real AWS, StackPort shows a warning banner and operates in read-only mode unless writes are explicitly enabled.
 
 ### Docker Compose (MiniStack + StackPort)
@@ -124,6 +127,30 @@ See [`examples/docker-compose.multi-endpoint.yml`](examples/docker-compose.multi
 
 The endpoint selector appears in the sidebar when more than one endpoint is configured. Each endpoint is health-checked independently, and all API requests, caches, and WebSocket subscriptions are scoped to the active endpoint.
 
+### Per-endpoint authentication
+
+Each endpoint can use its own AWS authentication method, configured from the Settings UI:
+
+| Auth Type | Description | Use Case |
+|-----------|-------------|----------|
+| **Default** | Uses `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` env vars or instance role | Local emulators, EC2/ECS deployments |
+| **AWS Profile** | Uses a named profile from `~/.aws/config` | SSO, AssumeRole, multiple accounts |
+| **Static Credentials** | Per-endpoint access key and secret | Service accounts, cross-account access |
+
+**Profile auth** supports SSO, AssumeRole, and credential_process — anything `boto3.Session(profile_name=...)` handles. If your SSO token expires, StackPort returns a 401 with instructions to run `aws sso login --profile <name>`.
+
+**Docker users:** mount your AWS config to use profiles inside the container:
+
+```yaml
+services:
+  stackport:
+    image: davireis/stackport
+    volumes:
+      - ~/.aws:/root/.aws
+```
+
+You can test connections before saving using the "Test Connection" button in the add/edit endpoint dialog.
+
 ## Service Browsers
 
 ### Dedicated UIs (8 services)
@@ -205,6 +232,7 @@ Press `?` anywhere to see all shortcuts.
 | `STACKPORT_CACHE_TTL` | `5` | Seconds to cache service stats |
 | `STACKPORT_PROBE_WORKERS` | `10` | Max concurrent workers for service probing |
 | `STACKPORT_ENDPOINTS` | *(unset)* | Multiple endpoints: `local=http://localhost:4566,staging=http://...` |
+| `STACKPORT_DATA_DIR` | `~/.stackport` | Directory for persistent config (endpoints.json) |
 | `LOG_LEVEL` | `INFO` | Python log level (`DEBUG` shows healthcheck logs) |
 
 ## Supported Services (35)
@@ -228,8 +256,8 @@ cd ui && npm install && npm run dev
 cd ui && npm run build
 
 # Run tests
-python -m pytest tests/ -x --tb=short    # backend (262 tests)
-cd ui && npx vitest run                   # frontend (163 tests)
+python -m pytest tests/ -x --tb=short    # backend (362 tests)
+cd ui && npx vitest run                   # frontend (176 tests)
 
 # Typecheck & lint
 cd ui && npx tsc -b
@@ -250,6 +278,7 @@ backend/
   routes/
     stats.py       Service discovery with concurrent probing
     resources.py   Generic list/detail for all services
+    endpoints.py   Endpoint CRUD, health checks, profile listing
     tags.py        Unified tag management (21 types)
     s3.py          S3 file browser with write ops
     dynamodb.py    DynamoDB query/scan

stackport-0.3.0/backend/aws_client.py

@@ -0,0 +1,63 @@
+import functools
+
+import boto3
+
+from backend.config import (
+    AWS_ACCESS_KEY_ID,
+    AWS_REGION,
+    AWS_SECRET_ACCESS_KEY,
+    endpoint_store,
+)
+
+_UNSET = object()
+
+
+@functools.lru_cache(maxsize=256)
+def get_client(
+    service_name: str,
+    endpoint_url: str | None = _UNSET,
+    region: str | None = None,
+    auth_type: str = "default",
+    auth_profile: str | None = None,
+    auth_access_key_id: str | None = None,
+    auth_secret_access_key: str | None = None,
+):
+    """Return a boto3 client for the given service and endpoint.
+
+    Args:
+        service_name: AWS service name (e.g., "s3", "dynamodb")
+        endpoint_url: Endpoint URL. None means real AWS (no custom endpoint).
+                     Omitted (sentinel) means use default endpoint.
+        region: Per-endpoint region override. None means use global AWS_REGION.
+        auth_type: "default", "profile", or "credentials"
+        auth_profile: AWS profile name (for auth_type="profile")
+        auth_access_key_id: Access key (for auth_type="credentials")
+        auth_secret_access_key: Secret key (for auth_type="credentials")
+
+    Returns:
+        Configured boto3 client
+    """
+    url = endpoint_store.get_default_url() if endpoint_url is _UNSET else endpoint_url
+    resolved_region = region or AWS_REGION
+
+    if auth_type == "profile" and auth_profile:
+        session = boto3.Session(profile_name=auth_profile, region_name=resolved_region)
+    elif auth_type == "credentials" and auth_access_key_id and auth_secret_access_key:
+        session = boto3.Session(
+            aws_access_key_id=auth_access_key_id,
+            aws_secret_access_key=auth_secret_access_key,
+            region_name=resolved_region,
+        )
+    else:
+        session_kwargs: dict = {"region_name": resolved_region}
+        if AWS_ACCESS_KEY_ID is not None:
+            session_kwargs["aws_access_key_id"] = AWS_ACCESS_KEY_ID
+        if AWS_SECRET_ACCESS_KEY is not None:
+            session_kwargs["aws_secret_access_key"] = AWS_SECRET_ACCESS_KEY
+        session = boto3.Session(**session_kwargs)
+
+    client_kwargs: dict = {"service_name": service_name}
+    if url is not None:
+        client_kwargs["endpoint_url"] = url
+
+    return session.client(**client_kwargs)

{stackport-0.2.6 → stackport-0.3.0}/backend/cache.py

@@ -29,5 +29,17 @@ class TTLCache:
         with self._lock:
             self._store.pop(key, None)
 
+    def delete_by_prefix(self, prefix: str) -> int:
+        """Delete all keys starting with the given prefix.
+
+        Returns:
+            Number of keys deleted
+        """
+        with self._lock:
+            to_delete = [k for k in self._store if k.startswith(prefix)]
+            for k in to_delete:
+                del self._store[k]
+            return len(to_delete)
+
 
 cache = TTLCache()

{stackport-0.2.6 → stackport-0.3.0}/backend/config.py

@@ -1,10 +1,16 @@
 import logging
 import os
 from collections.abc import Mapping
+from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
 AWS_ENDPOINT_URL: str | None = os.environ.get("AWS_ENDPOINT_URL")  # None = real AWS
+
+# Remove AWS_ENDPOINT_URL from the process environment so boto3's internal
+# credential resolution (SSO, AssumeRole) doesn't route to a local emulator.
+if "AWS_ENDPOINT_URL" in os.environ:
+    del os.environ["AWS_ENDPOINT_URL"]
 AWS_REGION: str = os.environ.get("AWS_REGION", "us-east-1")
 AWS_ACCESS_KEY_ID: str | None = os.environ.get("AWS_ACCESS_KEY_ID")
 AWS_SECRET_ACCESS_KEY: str | None = os.environ.get("AWS_SECRET_ACCESS_KEY")
@@ -85,6 +91,17 @@ def _parse_endpoints() -> dict[str, str | None]:
 ENDPOINTS: dict[str, str | None] = _parse_endpoints()
 DEFAULT_ENDPOINT: str | None = next(iter(ENDPOINTS.values()))
 
+# Data directory for persistent config (endpoints.json, etc.)
+STACKPORT_DATA_DIR: Path = Path(os.environ.get("STACKPORT_DATA_DIR", Path.home() / ".stackport"))
+
+# Initialize endpoint store
+from backend.endpoint_store import EndpointStore
+
+endpoint_store = EndpointStore(
+    json_path=STACKPORT_DATA_DIR / "endpoints.json",
+    env_endpoints=ENDPOINTS,
+)
+
 
 _UNSET = object()
 

stackport-0.3.0/backend/endpoint_store.py

@@ -0,0 +1,409 @@
+"""Persistent endpoint configuration with runtime CRUD.
+
+Endpoints are stored in a JSON file with atomic writes. The store is thread-safe
+and supports env-var seeding on first run.
+"""
+
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import TypedDict
+
+logger = logging.getLogger(__name__)
+
+_UNSET = object()
+
+
+class EndpointEntry(TypedDict):
+    """Single endpoint configuration."""
+
+    url: str | None  # None means real AWS
+    source: str  # "env" or "user"
+    region: str | None  # Optional per-endpoint region override
+    auth_type: str  # "default", "profile", or "credentials"
+    auth_profile: str | None  # AWS profile name (when auth_type="profile")
+    auth_access_key_id: str | None  # (when auth_type="credentials")
+    auth_secret_access_key: str | None  # (when auth_type="credentials")
+
+
+class EndpointsConfig(TypedDict):
+    """JSON file format."""
+
+    version: int
+    default: str
+    deleted_env_names: list[str]
+    endpoints: dict[str, EndpointEntry]
+
+
+class EndpointStore:
+    """Thread-safe, persistent endpoint configuration store."""
+
+    def __init__(self, json_path: Path, env_endpoints: dict[str, str | None]):
+        """Initialize the store.
+
+        Args:
+            json_path: Path to the persistent JSON file
+            env_endpoints: Initial endpoints from STACKPORT_ENDPOINTS env var
+        """
+        self.json_path = json_path
+        self.env_endpoints = env_endpoints
+        self._lock = threading.RLock()
+        self._config: EndpointsConfig | None = None
+        self._load_or_initialize()
+
+    def _load_or_initialize(self) -> None:
+        """Load existing JSON or initialize from env vars."""
+        with self._lock:
+            if self.json_path.exists():
+                try:
+                    with open(self.json_path, "r", encoding="utf-8") as f:
+                        self._config = json.load(f)
+                    logger.info("Loaded endpoints from %s", self.json_path)
+                    # Seed any new env endpoints not already present or deleted
+                    self._seed_from_env()
+                except (json.JSONDecodeError, OSError) as e:
+                    logger.warning("Failed to load %s: %s. Initializing from env.", self.json_path, e)
+                    self._initialize_from_env()
+            else:
+                self._initialize_from_env()
+
+    def _initialize_from_env(self) -> None:
+        """Create initial config from env vars."""
+        endpoints: dict[str, EndpointEntry] = {}
+        for name, url in self.env_endpoints.items():
+            endpoints[name] = {
+                "url": url,
+                "source": "env",
+                "region": None,
+                "auth_type": "default",
+                "auth_profile": None,
+                "auth_access_key_id": None,
+                "auth_secret_access_key": None,
+            }
+
+        default_name = next(iter(self.env_endpoints.keys())) if self.env_endpoints else "default"
+        self._config = {
+            "version": 2,
+            "default": default_name,
+            "deleted_env_names": [],
+            "endpoints": endpoints,
+        }
+        self._save()
+        logger.info("Initialized endpoints from env: %s", list(self.env_endpoints.keys()))
+
+    def _seed_from_env(self) -> None:
+        """Add env endpoints that aren't present and weren't deleted."""
+        if not self._config:
+            return
+        self._migrate_v1_to_v2()
+        deleted = set(self._config["deleted_env_names"])
+        added = []
+        for name, url in self.env_endpoints.items():
+            if name not in self._config["endpoints"] and name not in deleted:
+                self._config["endpoints"][name] = {
+                    "url": url,
+                    "source": "env",
+                    "region": None,
+                    "auth_type": "default",
+                    "auth_profile": None,
+                    "auth_access_key_id": None,
+                    "auth_secret_access_key": None,
+                }
+                added.append(name)
+        if added:
+            self._save()
+            logger.info("Seeded new env endpoints: %s", added)
+
+    def _migrate_v1_to_v2(self) -> None:
+        """Migrate v1 config (no auth fields) to v2."""
+        if not self._config or self._config.get("version", 1) >= 2:
+            return
+        for entry in self._config["endpoints"].values():
+            entry.setdefault("auth_type", "default")
+            entry.setdefault("auth_profile", None)
+            entry.setdefault("auth_access_key_id", None)
+            entry.setdefault("auth_secret_access_key", None)
+        self._config["version"] = 2
+        self._save()
+        logger.info("Migrated endpoints config from v1 to v2 (added auth fields)")
+
+    def _save(self) -> None:
+        """Atomically write config to disk."""
+        if not self._config:
+            return
+        tmp_path = self.json_path.with_suffix(".tmp")
+        try:
+            self.json_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(tmp_path, "w", encoding="utf-8") as f:
+                json.dump(self._config, f, indent=2, ensure_ascii=False)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp_path, self.json_path)
+        except OSError as e:
+            logger.error("Failed to write %s: %s", self.json_path, e)
+            if tmp_path.exists():
+                try:
+                    tmp_path.unlink()
+                except OSError:
+                    pass
+            raise
+
+    def list_all(self) -> dict[str, EndpointEntry]:
+        """Return all endpoints."""
+        with self._lock:
+            if not self._config:
+                return {}
+            return dict(self._config["endpoints"])
+
+    def get_default_name(self) -> str:
+        """Return the default endpoint name."""
+        with self._lock:
+            if not self._config or not self._config["endpoints"]:
+                return "default"
+            return self._config["default"]
+
+    def get_default_url(self) -> str | None:
+        """Return the default endpoint URL."""
+        with self._lock:
+            if not self._config or not self._config["endpoints"]:
+                return None
+            default_name = self._config["default"]
+            entry = self._config["endpoints"].get(default_name)
+            return entry["url"] if entry else None
+
+    def get(self, name: str) -> EndpointEntry | None:
+        """Get a single endpoint by name."""
+        with self._lock:
+            if not self._config:
+                return None
+            return self._config["endpoints"].get(name)
+
+    def add(
+        self,
+        name: str,
+        url: str | None,
+        region: str | None = None,
+        auth_type: str = "default",
+        auth_profile: str | None = None,
+        auth_access_key_id: str | None = None,
+        auth_secret_access_key: str | None = None,
+    ) -> None:
+        """Add a new endpoint.
+
+        Raises:
+            ValueError: If name already exists or is invalid
+        """
+        with self._lock:
+            if not self._config:
+                raise RuntimeError("Config not initialized")
+            if name in self._config["endpoints"]:
+                raise ValueError(f"Endpoint '{name}' already exists")
+            if not name or not name.replace("-", "").replace("_", "").isalnum():
+                raise ValueError(f"Invalid endpoint name '{name}'")
+            if len(name) > 50:
+                raise ValueError(f"Endpoint name too long (max 50): '{name}'")
+
+            self._config["endpoints"][name] = {
+                "url": url,
+                "source": "user",
+                "region": region,
+                "auth_type": auth_type,
+                "auth_profile": auth_profile,
+                "auth_access_key_id": auth_access_key_id,
+                "auth_secret_access_key": auth_secret_access_key,
+            }
+            # If this is the first endpoint, make it default
+            if len(self._config["endpoints"]) == 1:
+                self._config["default"] = name
+            self._save()
+            logger.info("Added endpoint: %s → %s", name, url)
+
+    def update(
+        self,
+        name: str,
+        url: str | None | object = _UNSET,
+        region: str | None | object = _UNSET,
+        auth_type: str | object = _UNSET,
+        auth_profile: str | None | object = _UNSET,
+        auth_access_key_id: str | None | object = _UNSET,
+        auth_secret_access_key: str | None | object = _UNSET,
+    ) -> None:
+        """Update an existing endpoint.
+
+        Args:
+            name: Endpoint name
+            url: New URL (None to use real AWS, unset to keep current)
+            region: New region (None to clear, unset to keep current)
+            auth_type: Auth type ("default", "profile", "credentials")
+            auth_profile: AWS profile name
+            auth_access_key_id: Access key ID for credentials auth
+            auth_secret_access_key: Secret access key for credentials auth
+
+        Raises:
+            ValueError: If endpoint doesn't exist
+        """
+        with self._lock:
+            if not self._config:
+                raise RuntimeError("Config not initialized")
+            if name not in self._config["endpoints"]:
+                raise ValueError(f"Endpoint '{name}' not found")
+
+            entry = self._config["endpoints"][name]
+            if url is not _UNSET:
+                entry["url"] = url  # type: ignore
+            if region is not _UNSET:
+                entry["region"] = region  # type: ignore
+            if auth_type is not _UNSET:
+                entry["auth_type"] = auth_type  # type: ignore
+            if auth_profile is not _UNSET:
+                entry["auth_profile"] = auth_profile  # type: ignore
+            if auth_access_key_id is not _UNSET:
+                entry["auth_access_key_id"] = auth_access_key_id  # type: ignore
+            if auth_secret_access_key is not _UNSET:
+                entry["auth_secret_access_key"] = auth_secret_access_key  # type: ignore
+
+            self._save()
+            logger.info("Updated endpoint: %s", name)
+
+    def remove(self, name: str) -> None:
+        """Remove an endpoint.
+
+        Raises:
+            ValueError: If endpoint doesn't exist or is the last one
+        """
+        with self._lock:
+            if not self._config:
+                raise RuntimeError("Config not initialized")
+            if name not in self._config["endpoints"]:
+                raise ValueError(f"Endpoint '{name}' not found")
+            if len(self._config["endpoints"]) == 1:
+                raise ValueError("Cannot delete the last endpoint")
+
+            entry = self._config["endpoints"].pop(name)
+            # Track deleted env endpoints to prevent re-seeding
+            if entry["source"] == "env":
+                if name not in self._config["deleted_env_names"]:
+                    self._config["deleted_env_names"].append(name)
+
+            # If we deleted the default, pick a new one
+            if self._config["default"] == name:
+                self._config["default"] = next(iter(self._config["endpoints"].keys()))
+
+            self._save()
+            logger.info("Removed endpoint: %s", name)
+
+    def set_default(self, name: str) -> None:
+        """Set the default endpoint.
+
+        Raises:
+            ValueError: If endpoint doesn't exist
+        """
+        with self._lock:
+            if not self._config:
+                raise RuntimeError("Config not initialized")
+            if name not in self._config["endpoints"]:
+                raise ValueError(f"Endpoint '{name}' not found")
+
+            self._config["default"] = name
+            self._save()
+            logger.info("Set default endpoint: %s", name)
+
+    def resolve(self, endpoint_name_or_url: str | None) -> str | None:
+        """Resolve an endpoint name or URL to a URL.
+
+        Args:
+            endpoint_name_or_url: Endpoint name, direct URL, or None
+
+        Returns:
+            - If None: returns default URL
+            - If starts with http:// or https://: returns as-is (direct URL)
+            - Otherwise: looks up name and returns URL, or default if not found
+        """
+        with self._lock:
+            if not self._config:
+                return None
+
+            # None → default
+            if endpoint_name_or_url is None:
+                return self.get_default_url()
+
+            # Direct URL passthrough
+            if endpoint_name_or_url.startswith("http://") or endpoint_name_or_url.startswith("https://"):
+                return endpoint_name_or_url
+
+            # Look up by name
+            entry = self._config["endpoints"].get(endpoint_name_or_url)
+            if entry:
+                return entry["url"]
+
+            # Fallback to default
+            return self.get_default_url()
+
+    def resolve_with_region(self, endpoint_name_or_url: str | None) -> tuple[str | None, str | None]:
+        """Resolve an endpoint to both URL and region.
+
+        Unlike resolve(), this preserves the endpoint name → region mapping,
+        avoiding ambiguity when multiple endpoints share the same URL.
+
+        Returns:
+            Tuple of (url, region). Region is None if not set.
+        """
+        with self._lock:
+            if not self._config:
+                return None, None
+
+            if endpoint_name_or_url is None:
+                default_name = self._config["default"]
+                entry = self._config["endpoints"].get(default_name)
+                if entry:
+                    return entry["url"], entry.get("region")
+                return None, None
+
+            if endpoint_name_or_url.startswith("http://") or endpoint_name_or_url.startswith("https://"):
+                return endpoint_name_or_url, None
+
+            entry = self._config["endpoints"].get(endpoint_name_or_url)
+            if entry:
+                return entry["url"], entry.get("region")
+
+            default_name = self._config["default"]
+            default_entry = self._config["endpoints"].get(default_name)
+            if default_entry:
+                return default_entry["url"], default_entry.get("region")
+            return None, None
+
+    def resolve_full(self, endpoint_name_or_url: str | None) -> EndpointEntry | None:
+        """Resolve an endpoint to the full entry including auth info.
+
+        Returns:
+            Full EndpointEntry or None if not found.
+        """
+        with self._lock:
+            if not self._config:
+                return None
+
+            if endpoint_name_or_url is None:
+                default_name = self._config["default"]
+                return self._config["endpoints"].get(default_name)
+
+            if endpoint_name_or_url.startswith("http://") or endpoint_name_or_url.startswith("https://"):
+                return None
+
+            entry = self._config["endpoints"].get(endpoint_name_or_url)
+            if entry:
+                return entry
+
+            default_name = self._config["default"]
+            return self._config["endpoints"].get(default_name)
+
+    def get_region_for_url(self, url: str | None) -> str | None:
+        """Look up the per-endpoint region for a given URL."""
+        with self._lock:
+            if not self._config:
+                return None
+            for entry in self._config["endpoints"].values():
+                if entry["url"] == url:
+                    return entry.get("region")
+            return None