bc-cli 0.1.0__py3-none-any.whl

bcli/_url.py

@@ -0,0 +1,133 @@
+"""URL builder for Business Central API endpoints."""
+
+from __future__ import annotations
+
+from bcli.config._defaults import BC_BASE_URL, BC_STANDARD_API_PATH
+
+
+def build_url(
+    *,
+    environment: str,
+    company_id: str,
+    entity_set_name: str,
+    record_id: str | None = None,
+    # For custom APIs — None means standard v2.0
+    publisher: str | None = None,
+    group: str | None = None,
+    version: str | None = None,
+) -> str:
+    """Build a full BC API URL.
+
+    Standard v2.0:
+        https://api.businesscentral.dynamics.com/v2.0/{env}/api/v2.0/companies({id})/{entity}
+
+    Custom API:
+        https://api.businesscentral.dynamics.com/v2.0/{env}/api/{pub}/{grp}/{ver}/companies({id})/{entity}
+    """
+    if publisher and group and version:
+        api_path = f"api/{publisher}/{group}/{version}"
+    else:
+        api_path = BC_STANDARD_API_PATH
+
+    url = f"{BC_BASE_URL}/{environment}/{api_path}/companies({company_id})/{entity_set_name}"
+
+    if record_id:
+        url = f"{url}({record_id})"
+
+    return url
+
+
+def build_companies_url(*, environment: str) -> str:
+    """Build URL to list companies (no company context needed)."""
+    return f"{BC_BASE_URL}/{environment}/{BC_STANDARD_API_PATH}/companies"
+
+
+def build_environments_url(*, tenant_id: str) -> str:
+    """Build URL for BC Admin Center environments API."""
+    return (
+        "https://api.businesscentral.dynamics.com"
+        "/admin/v2.1/applications/businesscentral/environments"
+    )
+
+
+def build_metadata_url(
+    *,
+    environment: str,
+    publisher: str | None = None,
+    group: str | None = None,
+    version: str | None = None,
+) -> str:
+    """Build URL for OData $metadata endpoint."""
+    if publisher and group and version:
+        api_path = f"api/{publisher}/{group}/{version}"
+    else:
+        api_path = BC_STANDARD_API_PATH
+    return f"{BC_BASE_URL}/{environment}/{api_path}/$metadata"
+
+
+# ─── Host allowlist for absolute URLs ─────────────────────────────────────
+#
+# bcli attaches a BC bearer token to every outgoing request. If a BC
+# response ever returns an off-origin ``@odata.nextLink`` (e.g. a
+# compromised custom-API page that returns ``@odata.nextLink:
+# https://attacker.example/leak``), the paginator would happily follow it
+# with the token attached, leaking the credential to the attacker. Guard
+# the paginator (and any other absolute-URL follower) by running absolute
+# URLs through ``assert_bc_origin`` before they reach the bearer-injecting
+# transport.
+#
+# We allow the entire ``.businesscentral.dynamics.com`` suffix because BC
+# is regional — ``api.businesscentral.dynamics.com`` for the API,
+# ``api.bc.dynamics.com`` for the legacy alias, plus customer-specific
+# regional CNAMEs that all live under the same parent suffix. The leading
+# dot prevents the classic ``evilbusinesscentral.dynamics.com.attacker``
+# trick.
+
+# Suffix list is ordered most-specific-first; a hostname matches if it
+# equals the suffix or ends with ``"." + suffix``.
+_ALLOWED_HOST_SUFFIXES: tuple[str, ...] = (
+    "businesscentral.dynamics.com",
+    "bc.dynamics.com",
+)
+
+
+def is_bc_origin(url: str) -> bool:
+    """Return ``True`` if ``url`` is absolute and points at a BC host.
+
+    Relative URLs (no scheme) are considered safe — they get joined to the
+    SDK's BC base URL by httpx, so they can't leak auth elsewhere.
+    """
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        # Relative URL — caller will resolve it against the BC base URL.
+        return True
+    if parsed.scheme not in ("http", "https"):
+        return False
+    host = (parsed.hostname or "").lower()
+    if not host:
+        return False
+    for suffix in _ALLOWED_HOST_SUFFIXES:
+        if host == suffix or host.endswith("." + suffix):
+            return True
+    return False
+
+
+def assert_bc_origin(url: str) -> None:
+    """Raise ``ValueError`` if ``url`` isn't a relative URL or BC host.
+
+    Called by the transport layer before an absolute URL reaches the
+    bearer-injecting request path. The error message intentionally
+    surfaces the rejected URL so the operator can audit a misbehaving
+    endpoint or registry entry.
+    """
+    if not is_bc_origin(url):
+        raise ValueError(
+            f"Refusing to attach BC credentials to off-origin URL: {url!r}. "
+            f"Allowed host suffixes: {list(_ALLOWED_HOST_SUFFIXES)}. "
+            f"This URL came from an @odata.nextLink or similar follow-up "
+            f"reference; if the BC tenant is genuinely returning it, the "
+            f"allowlist needs to be expanded — but check first that the "
+            f"response wasn't tampered with."
+        )

bcli/_version.py

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

bcli/auth/__init__.py

@@ -0,0 +1,8 @@
+"""Authentication providers for Business Central."""
+
+from bcli.auth._base import AuthProvider
+from bcli.auth._browser import BrowserAuth
+from bcli.auth._credentials import ClientCredentialsAuth
+from bcli.auth._token_cache import TokenCache
+
+__all__ = ["AuthProvider", "BrowserAuth", "ClientCredentialsAuth", "TokenCache"]

bcli/auth/_base.py

@@ -0,0 +1,17 @@
+"""Auth provider protocol."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class AuthProvider(Protocol):
+    """Protocol for authentication providers."""
+
+    async def get_access_token(self) -> str:
+        """Return a valid access token, refreshing if needed."""
+        ...
+
+    def clear_cache(self) -> None:
+        """Clear any cached tokens."""
+        ...

bcli/auth/_browser.py

@@ -0,0 +1,234 @@
+"""Authorization code flow with PKCE for interactive browser-based auth.
+
+Opens the user's default browser to authenticate. A temporary localhost server
+catches the redirect callback. The token carries the user's identity, so
+Business Central enforces their permission sets on every API call.
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import subprocess
+import sys
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+import msal
+
+from bcli.auth._token_cache import TokenCache
+from bcli.config._defaults import BC_SCOPE, ENTRA_AUTHORITY_BASE
+from bcli.errors import AuthError
+
+logger = logging.getLogger(__name__)
+
+_AUTH_TIMEOUT = 120  # seconds to wait for browser callback
+_DEFAULT_PORT = 8400  # fixed port — register http://localhost:8400 in Entra ID
+
+
+def _open_browser(url: str, *, incognito: bool = False) -> None:
+    """Open a URL in the browser, optionally in incognito/private mode."""
+    if not incognito:
+        webbrowser.open(url)
+        return
+
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            # Try Chrome first, fall back to Safari private
+            for app, flag in [
+                ("/Applications/Google Chrome.app", "--incognito"),
+                ("/Applications/Microsoft Edge.app", "--inprivate"),
+                ("/Applications/Brave Browser.app", "--incognito"),
+            ]:
+                try:
+                    subprocess.Popen([
+                        "open", "-na", app, "--args", flag, url,
+                    ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                    return
+                except (FileNotFoundError, OSError):
+                    continue
+            # Safari doesn't support incognito via CLI, fall back to default
+            webbrowser.open(url)
+        elif system == "Windows":
+            for exe, flag in [
+                ("chrome", "--incognito"),
+                ("msedge", "--inprivate"),
+            ]:
+                try:
+                    subprocess.Popen([exe, flag, url])
+                    return
+                except FileNotFoundError:
+                    continue
+            webbrowser.open(url)
+        else:
+            # Linux
+            for exe, flag in [
+                ("google-chrome", "--incognito"),
+                ("chromium-browser", "--incognito"),
+                ("firefox", "--private-window"),
+            ]:
+                try:
+                    subprocess.Popen([exe, flag, url])
+                    return
+                except FileNotFoundError:
+                    continue
+            webbrowser.open(url)
+    except Exception:
+        webbrowser.open(url)
+
+
+class BrowserAuth:
+    """Interactive browser-based auth via authorization code flow with PKCE.
+
+    User authenticates as themselves — BC enforces their permission sets.
+    """
+
+    def __init__(
+        self,
+        *,
+        tenant_id: str,
+        client_id: str,
+        token_cache: TokenCache | None = None,
+        login_hint: str | None = None,
+        incognito: bool = False,
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._client_id = client_id
+        self._token_cache = token_cache or TokenCache()
+        self._authority = f"{ENTRA_AUTHORITY_BASE}/{tenant_id}"
+        self._login_hint = login_hint
+        self._incognito = incognito
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, using cache or browser flow."""
+        # Check disk cache first
+        cached = self._token_cache.get(self._tenant_id, self._client_id)
+        if cached:
+            return cached
+
+        # Build MSAL public client
+        app = msal.PublicClientApplication(
+            client_id=self._client_id,
+            authority=self._authority,
+        )
+
+        # Try silent acquisition from MSAL in-memory cache
+        accounts = app.get_accounts()
+        if accounts:
+            result = app.acquire_token_silent(
+                scopes=[BC_SCOPE],
+                account=accounts[0],
+            )
+            if result and "access_token" in result:
+                self._cache_token(result)
+                return result["access_token"]
+
+        # Start browser auth flow
+        port = _DEFAULT_PORT
+        redirect_uri = f"http://localhost:{port}"
+
+        # MSAL handles PKCE automatically via initiate_auth_code_flow
+        flow_kwargs: dict[str, str] = {}
+        if self._login_hint:
+            # Pre-fill the email and skip account picker (coming from WorkOS)
+            flow_kwargs["login_hint"] = self._login_hint
+        else:
+            # Standalone browser auth — show account picker
+            flow_kwargs["prompt"] = "select_account"
+
+        flow = app.initiate_auth_code_flow(
+            scopes=[BC_SCOPE],
+            redirect_uri=redirect_uri,
+            **flow_kwargs,
+        )
+
+        if "auth_uri" not in flow:
+            raise AuthError(
+                f"Failed to initiate browser auth: {flow.get('error_description', 'Unknown error')}",
+                status_code=401,
+            )
+
+        # Start localhost server to catch the callback
+        auth_response: dict[str, Any] = {}
+        server_error: list[str] = []
+
+        class CallbackHandler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                parsed = urlparse(self.path)
+                params = parse_qs(parsed.query)
+                # Flatten single-value params
+                auth_response.update({k: v[0] if len(v) == 1 else v for k, v in params.items()})
+
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html")
+                self.end_headers()
+
+                if "error" in params:
+                    error_msg = params.get("error_description", params.get("error", ["Unknown"]))[0]
+                    server_error.append(error_msg)
+                    self.wfile.write(
+                        b"<html><body><h2>Authentication failed</h2>"
+                        b"<p>You can close this tab.</p></body></html>"
+                    )
+                else:
+                    self.wfile.write(
+                        b"<html><body><h2>Authenticated successfully</h2>"
+                        b"<p>You can close this tab and return to the terminal.</p></body></html>"
+                    )
+
+            def log_message(self, format: str, *args: object) -> None:
+                pass  # Suppress HTTP server logs
+
+        server = HTTPServer(("127.0.0.1", port), CallbackHandler)
+        server.timeout = _AUTH_TIMEOUT
+
+        # Open browser
+        auth_url = flow["auth_uri"]
+        mode = " (incognito)" if self._incognito else ""
+        print(f"\nOpening browser for authentication{mode}...", file=sys.stderr)
+        print(f"If the browser doesn't open, visit:\n  {auth_url}\n", file=sys.stderr)
+        _open_browser(auth_url, incognito=self._incognito)
+
+        # Wait for single callback request
+        server_thread = threading.Thread(target=server.handle_request, daemon=True)
+        server_thread.start()
+        server_thread.join(timeout=_AUTH_TIMEOUT)
+        server.server_close()
+
+        if not auth_response:
+            raise AuthError(
+                f"Browser authentication timed out after {_AUTH_TIMEOUT} seconds. "
+                "Try 'bcli auth login --method device' as a fallback.",
+                status_code=401,
+            )
+
+        if server_error:
+            raise AuthError(
+                f"Browser authentication failed: {server_error[0]}",
+                status_code=401,
+            )
+
+        # Exchange auth code for token
+        result = app.acquire_token_by_auth_code_flow(flow, auth_response)
+
+        if "access_token" not in result:
+            error_desc = result.get("error_description", result.get("error", "Unknown error"))
+            raise AuthError(f"Token acquisition failed: {error_desc}", status_code=401)
+
+        self._cache_token(result)
+        logger.info("Acquired BC API token via browser auth flow")
+        return result["access_token"]
+
+    def _cache_token(self, result: dict) -> None:
+        """Cache the token to disk."""
+        access_token = result["access_token"]
+        expires_in = result.get("expires_in", 3600)
+        self._token_cache.put(self._tenant_id, self._client_id, access_token, expires_in)
+
+    def clear_cache(self) -> None:
+        """Clear cached tokens for this tenant/client."""
+        self._token_cache.clear(self._tenant_id, self._client_id)

bcli/auth/_credentials.py

@@ -0,0 +1,169 @@
+"""Client credentials auth flow using MSAL."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import msal
+
+from bcli.auth._token_cache import TokenCache
+from bcli.config._defaults import BC_SCOPE, ENTRA_AUTHORITY_BASE
+from bcli.errors import AuthError, ConfigError
+
+logger = logging.getLogger(__name__)
+
+
+def _try_keyring_get(service: str, username: str) -> str | None:
+    """Try to get a secret from the OS keychain. Returns None if keyring unavailable."""
+    try:
+        import keyring
+
+        return keyring.get_password(service, username)
+    except Exception:
+        return None
+
+
+def _try_keyring_set(service: str, username: str, password: str) -> bool:
+    """Try to store a secret in the OS keychain. Returns True on success."""
+    try:
+        import keyring
+
+        keyring.set_password(service, username, password)
+        return True
+    except Exception:
+        return False
+
+
+def _try_keyring_delete(service: str, username: str) -> bool:
+    """Try to delete a secret from the OS keychain."""
+    try:
+        import keyring
+
+        keyring.delete_password(service, username)
+        return True
+    except Exception:
+        return False
+
+
+KEYRING_SERVICE = "bcli"
+
+
+class ClientCredentialsAuth:
+    """Service-to-service auth via OAuth2 client credentials flow.
+
+    Secret resolution is lazy — only resolved when a new token is needed.
+    Resolution order:
+    1. Direct client_secret parameter
+    2. OS keychain (via keyring library)
+    3. Environment variable (client_secret_env)
+    4. Error
+    """
+
+    def __init__(
+        self,
+        *,
+        tenant_id: str,
+        client_id: str,
+        client_secret: str | None = None,
+        client_secret_env: str | None = None,
+        token_cache: TokenCache | None = None,
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._client_id = client_id
+        self._token_cache = token_cache or TokenCache()
+        self._client_secret = client_secret  # May be None — resolved lazily
+        self._client_secret_env = client_secret_env
+        self._authority = f"{ENTRA_AUTHORITY_BASE}/{tenant_id}"
+
+    def _resolve_secret(self) -> str:
+        """Resolve the client secret. Only called when a new token is needed."""
+        # 1. Already provided directly
+        if self._client_secret:
+            return self._client_secret
+
+        # 2. Try OS keychain
+        keyring_key = f"{self._tenant_id}:{self._client_id}"
+        secret = _try_keyring_get(KEYRING_SERVICE, keyring_key)
+        if secret:
+            logger.debug("Resolved client secret from OS keychain")
+            return secret
+
+        # 3. Try environment variable
+        if self._client_secret_env:
+            secret = os.environ.get(self._client_secret_env)
+            if secret:
+                return secret
+
+        # 4. Try generic fallback env var
+        secret = os.environ.get("BCLI_CLIENT_SECRET") or os.environ.get("BCLI_SECRET")
+        if secret:
+            return secret
+
+        # Nothing found
+        hints = []
+        hints.append("bcli auth store-secret  (saves to OS keychain)")
+        if self._client_secret_env:
+            hints.append(f"export {self._client_secret_env}=<secret>")
+        raise ConfigError(
+            "No client secret found. Options:\n  " + "\n  ".join(hints)
+        )
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, using cache if available."""
+        # Check disk cache first — no secret needed
+        cached = self._token_cache.get(self._tenant_id, self._client_id)
+        if cached:
+            return cached
+
+        # Need a new token — resolve secret now
+        secret = self._resolve_secret()
+
+        app = msal.ConfidentialClientApplication(
+            client_id=self._client_id,
+            authority=self._authority,
+            client_credential=secret,
+        )
+
+        result = app.acquire_token_for_client(scopes=[BC_SCOPE])
+
+        if "access_token" not in result:
+            error_desc = result.get("error_description", result.get("error", "Unknown error"))
+            raise AuthError(
+                f"Failed to acquire token: {error_desc}",
+                status_code=401,
+            )
+
+        access_token = result["access_token"]
+        expires_in = result.get("expires_in", 3600)
+
+        self._token_cache.put(self._tenant_id, self._client_id, access_token, expires_in)
+
+        logger.info("Acquired new BC API access token")
+        return access_token
+
+    def clear_cache(self) -> None:
+        """Clear cached tokens for this tenant/client."""
+        self._token_cache.clear(self._tenant_id, self._client_id)
+
+    @staticmethod
+    def store_secret(tenant_id: str, client_id: str, secret: str) -> bool:
+        """Store a client secret in the OS keychain."""
+        keyring_key = f"{tenant_id}:{client_id}"
+        return _try_keyring_set(KEYRING_SERVICE, keyring_key, secret)
+
+    @staticmethod
+    def delete_secret(tenant_id: str, client_id: str) -> bool:
+        """Delete a client secret from the OS keychain."""
+        keyring_key = f"{tenant_id}:{client_id}"
+        return _try_keyring_delete(KEYRING_SERVICE, keyring_key)
+
+    @staticmethod
+    def has_keyring() -> bool:
+        """Check if the keyring library is available."""
+        try:
+            import keyring  # noqa: F401
+
+            return True
+        except ImportError:
+            return False

bcli/auth/_device_code.py

@@ -0,0 +1,90 @@
+"""Device code auth flow for interactive CLI use."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import msal
+
+from bcli.auth._token_cache import TokenCache
+from bcli.config._defaults import BC_SCOPE, ENTRA_AUTHORITY_BASE
+from bcli.errors import AuthError
+
+logger = logging.getLogger(__name__)
+
+
+class DeviceCodeAuth:
+    """Interactive device code flow — user authenticates via browser.
+
+    Used for CLI interactive sessions where the user is present.
+    """
+
+    def __init__(
+        self,
+        *,
+        tenant_id: str,
+        client_id: str,
+        token_cache: TokenCache | None = None,
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._client_id = client_id
+        self._token_cache = token_cache or TokenCache()
+        self._authority = f"{ENTRA_AUTHORITY_BASE}/{tenant_id}"
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, using cache or device code flow."""
+        # Check disk cache first
+        cached = self._token_cache.get(self._tenant_id, self._client_id)
+        if cached:
+            return cached
+
+        # Build MSAL public client (no client_secret needed)
+        app = msal.PublicClientApplication(
+            client_id=self._client_id,
+            authority=self._authority,
+        )
+
+        # Try silent acquisition first (MSAL in-memory cache from prior flows)
+        accounts = app.get_accounts()
+        if accounts:
+            result = app.acquire_token_silent(
+                scopes=[BC_SCOPE],
+                account=accounts[0],
+            )
+            if result and "access_token" in result:
+                self._cache_token(result)
+                return result["access_token"]
+
+        # Initiate device code flow
+        flow = app.initiate_device_flow(scopes=[BC_SCOPE])
+
+        if "user_code" not in flow:
+            raise AuthError(
+                f"Device code flow failed: {flow.get('error_description', 'Unknown error')}",
+                status_code=401,
+            )
+
+        # Print the device code message for the user
+        print(f"\n{flow['message']}\n", file=sys.stderr)
+
+        # Block until user completes browser auth
+        result = app.acquire_token_by_device_flow(flow)
+
+        if "access_token" not in result:
+            error_desc = result.get("error_description", result.get("error", "Unknown error"))
+            raise AuthError(f"Device code auth failed: {error_desc}", status_code=401)
+
+        self._cache_token(result)
+        logger.info("Acquired BC API token via device code flow")
+        return result["access_token"]
+
+    def _cache_token(self, result: dict) -> None:
+        """Cache the token to disk."""
+        access_token = result["access_token"]
+        expires_in = result.get("expires_in", 3600)
+        self._token_cache.put(self._tenant_id, self._client_id, access_token, expires_in)
+
+    def clear_cache(self) -> None:
+        """Clear cached tokens for this tenant/client."""
+        self._token_cache.clear(self._tenant_id, self._client_id)