fileroute 0.1.2__py3-none-any.whl

fileroute/__init__.py

@@ -0,0 +1,13 @@
+from .clients import get_provider
+from .models import Catalog, Resource, Location, CatalogReference, ServiceType
+from .exceptions import AmbiguousPathError
+
+__all__ = [
+    "ServiceType",
+    "get_provider",
+    "Catalog",
+    "Resource",
+    "Location",
+    "CatalogReference",
+    "AmbiguousPathError",
+]

fileroute/auth/__init__.py

@@ -0,0 +1,17 @@
+from fileroute.auth.google import (
+    GoogleAuth,
+)
+from fileroute.auth.microsoft import (
+    MicrosoftAuth
+)
+from fileroute.auth.settings import (
+    GoogleAuthConfig,
+    MicrosoftAuthConfig,
+)
+
+__all__ = [
+    "GoogleAuth",
+    "GoogleAuthConfig",
+    "MicrosoftAuth",
+    "MicrosoftAuthConfig"
+]

fileroute/auth/google.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Sequence
+
+import google.auth
+from google.auth.credentials import Credentials
+from google.oauth2.credentials import Credentials as UserCredentials
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+from google_auth_oauthlib.flow import InstalledAppFlow
+from fileroute.exceptions import GoogleAuthError,GoogleRefreshError
+from warnings import warn
+
+DEFAULT_DRIVE_SCOPES = ("https://www.googleapis.com/auth/drive",)
+DEFAULT_DRIVE_READONLY_SCOPES = (
+    "https://www.googleapis.com/auth/drive.readonly",
+)
+
+
+def normalize_google_scopes(
+    scopes: Sequence[str] | str | None,
+    *,
+    default: Sequence[str] = DEFAULT_DRIVE_SCOPES,
+) -> list[str]:
+    if scopes is None:
+        return list(default)
+    if isinstance(scopes, str):
+        return [scopes]
+    normalized = [scope for scope in scopes if scope]
+    return normalized or list(default)
+
+
+class GoogleAuth:
+    """Google credential holder with named constructors for each auth mode.
+
+    The primary entry points are the ``from_*`` class methods. The
+    ``__init__`` constructor accepts a raw :class:`~google.auth.credentials.Credentials`
+    object and acts as a low-level escape hatch (e.g. for tests).
+
+    Usage::
+
+        # Application Default Credentials (default for most deployments)
+        auth = GoogleAuth.from_adc()
+
+        # Service account JSON key file
+        auth = GoogleAuth.from_service_account("path/to/key.json")
+
+        # Interactive OAuth (installed-app flow)
+        auth = GoogleAuth.from_user_oauth("path/to/client_secrets.json")
+
+        # Read mode + scopes from environment variables / .env file
+        auth = GoogleAuth.from_settings()
+    """
+
+    def __init__(self, credentials: Credentials) -> None:
+        """Low-level escape hatch: supply raw credentials directly."""
+        self._creds = credentials
+
+    def refresh(self) -> None:
+        """Refresh the access token"""
+        self._creds.refresh(Request())
+
+    @classmethod
+    def from_adc(cls, scopes: Sequence[str] | str | None = None) -> "GoogleAuth":
+        """Build from Application Default Credentials (``gcloud auth application-default login``)."""
+        normalized_scopes = normalize_google_scopes(scopes)
+        try:
+            creds, _project = google.auth.default(scopes=normalized_scopes)
+            if getattr(creds, "requires_scopes", False) and hasattr(creds, "with_scopes"):
+                creds = creds.with_scopes(normalized_scopes)
+            return cls(creds)
+        except Exception as exc:
+            raise GoogleAuthError(
+                "Failed to load Application Default Credentials: "
+                f"{exc}. To use fileroute user OAuth instead, set "
+                "GOOGLE_AUTH_MODE=user_oauth with GOOGLE_OAUTH_CREDENTIALS "
+                "and run 'fileroute auth login gdrive'."
+            ) from exc
+
+    @classmethod
+    def from_service_account(
+        cls,
+        credentials_path: str | Path,
+        scopes: Sequence[str] | str | None = None,
+    ) -> "GoogleAuth":
+        """Build from a service account JSON key file."""
+        normalized_scopes = normalize_google_scopes(scopes)
+        try:
+            creds = service_account.Credentials.from_service_account_file(
+                str(credentials_path),
+                scopes=normalized_scopes,
+            )
+            return cls(creds)
+        except Exception as exc:
+            raise GoogleAuthError(
+                f"Failed to load service account credentials from {credentials_path}: {exc}"
+            ) from exc
+
+
+    @classmethod
+    def from_user_oauth(
+        cls,
+        scopes: Sequence[str] | str,
+        client_secrets_path: str | Path = None,
+        token_path: str | Path = None,
+        token_store: Any = None,
+    ) -> "GoogleAuth":
+        """Build via the OAuth installed-app flow, with token persistence."""
+    
+        def _interactive_login_from_client_secrets_file() -> UserCredentials:
+            flow = InstalledAppFlow.from_client_secrets_file(
+                                str(client_secrets_path),
+                                scopes=normalized_scopes,
+                            )
+            creds = flow.run_local_server(port=0)
+            return creds
+
+        normalized_scopes = normalize_google_scopes(scopes)
+        if token_store is not None:
+            creds = token_store.load()
+            if creds is not None and getattr(creds, "valid", False):
+                return cls(creds)
+            if creds is not None and getattr(creds, "refresh_token", None):
+                creds.refresh(Request())
+            elif client_secrets_path:
+                creds = _interactive_login_from_client_secrets_file()
+            else:
+                raise GoogleAuthError(
+                    "client_secrets_path is required when stored OAuth credentials are missing."
+                )
+            token_store.save(creds)
+            return cls(creds)
+
+        if Path(token_path).exists():
+            creds = UserCredentials.from_authorized_user_file(token_path, scopes=scopes)
+            try:
+                creds.refresh(Request())
+                
+            except GoogleRefreshError as exc:
+                warn(f"Failed to refresh stored credentials: {exc}. Proceeding to interactive login.")
+                creds = _interactive_login_from_client_secrets_file()
+        elif client_secrets_path:
+            warn(f"Token file does not exist at {token_path}. Credentials will not be saved for future use.")
+            creds = _interactive_login_from_client_secrets_file()
+        else:
+            raise GoogleAuthError("At least one of token_path or client_secrets_path must be provided for user OAuth.")
+        
+        if hasattr(creds, "to_json"):
+            Path(token_path).parent.mkdir(parents=True, exist_ok=True)
+            Path(token_path).write_text(creds.to_json())
+        return cls(creds)
+
+    @classmethod
+    def from_settings(cls, config: object | None = None) -> "GoogleAuth":
+        """Build from environment variables or a :class:`~fileroute.auth.settings.GoogleAuthConfig`.
+
+        When *config* is ``None`` the settings are read from the environment
+        (and any ``.env`` file in the working directory).
+        """
+        from fileroute.auth.settings import GoogleAuthConfig
+
+        resolved: GoogleAuthConfig = config if config is not None else GoogleAuthConfig()  # type: ignore[assignment]
+        return resolved.to_auth()
+
+    @property
+    def credentials(self) -> Credentials:
+        """The underlying :class:`~google.auth.credentials.Credentials` object."""
+        return self._creds
+
+    def ensure_valid(self) -> None:
+        """Refresh credentials when the current token is not valid."""
+        if not self._creds.valid:
+            self.refresh()
+
+__all__ = [
+    "GoogleAuth"
+]

fileroute/auth/microsoft.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+import msal
+
+from fileroute.exceptions import GraphAuthError
+
+DEFAULT_MICROSOFT_GRAPH_SCOPES = ("https://graph.microsoft.com/.default",)
+
+
+def normalize_microsoft_scopes(
+    scopes: Sequence[str] | str | None,
+    *,
+    default: Sequence[str] = DEFAULT_MICROSOFT_GRAPH_SCOPES,
+) -> list[str]:
+    if scopes is None:
+        return list(default)
+    if isinstance(scopes, str):
+        normalized = [scope.strip() for scope in scopes.split(",") if scope.strip()]
+        return normalized or list(default)
+    normalized = [scope for scope in scopes if scope]
+    return normalized or list(default)
+
+
+def _extract_access_token(result: dict[str, object]) -> str:
+    token = result.get("access_token")
+    if isinstance(token, str) and token:
+        return token
+    raise GraphAuthError(f"Token error: {result.get('error_description')}")
+
+
+class MicrosoftAuth:
+    """Microsoft access-token holder with named constructors for each auth mode.
+
+    The primary entry points are the ``from_*`` class methods. The
+    ``__init__`` constructor accepts a raw access token string and acts as a
+    low-level escape hatch (e.g. for tests).
+
+    Usage::
+
+        # App-only (client credentials) – most common for server-side automation
+        auth = MicrosoftAuth.from_app_only(tenant_id, client_id, client_secret)
+
+        # Delegated (interactive browser login)
+        auth = MicrosoftAuth.from_delegated(tenant_id, client_id)
+
+        # Read mode + credentials from environment variables / .env file
+        auth = MicrosoftAuth.from_settings()
+    """
+
+    def __init__(self, access_token: str) -> None:
+        """Low-level escape hatch: supply a raw access token directly."""
+        self._access_token = access_token
+
+    # ------------------------------------------------------------------
+    # Named constructors
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_app_only(
+        cls,
+        tenant_id: str,
+        client_id: str,
+        client_secret: str,
+        scopes: Sequence[str] | str | None = None,
+    ) -> "MicrosoftAuth":
+        """Build using client-credential (app-only) flow via MSAL."""
+        if not client_secret:
+            raise GraphAuthError(
+                "client_secret is required for Microsoft app_only mode."
+            )
+        normalized_scopes = normalize_microsoft_scopes(scopes)
+        authority = f"https://login.microsoftonline.com/{tenant_id}"
+        app = msal.ConfidentialClientApplication(
+            client_id=client_id,
+            client_credential=client_secret,
+            authority=authority,
+        )
+        result = app.acquire_token_for_client(scopes=normalized_scopes)
+        return cls(_extract_access_token(result))
+
+    @classmethod
+    def from_delegated(
+        cls,
+        tenant_id: str,
+        client_id: str,
+        scopes: Sequence[str] | str | None = None,
+    ) -> "MicrosoftAuth":
+        """Build using interactive delegated (user) flow via MSAL."""
+        normalized_scopes = normalize_microsoft_scopes(scopes)
+        authority = f"https://login.microsoftonline.com/{tenant_id}"
+        app = msal.PublicClientApplication(client_id, authority=authority)
+        accounts = app.get_accounts()
+        if accounts:
+            result = app.acquire_token_silent(normalized_scopes, account=accounts[0])
+            if result and "access_token" in result:
+                return cls(_extract_access_token(result))
+        result = app.acquire_token_interactive(scopes=normalized_scopes)
+        return cls(_extract_access_token(result))
+
+    @classmethod
+    def from_settings(cls, config: object | None = None) -> "MicrosoftAuth":
+        """Build from environment variables or a :class:`~fileroute.auth.settings.MicrosoftAuthConfig`.
+
+        When *config* is ``None`` the settings are read from the environment
+        (and any ``.env`` file in the working directory).
+        """
+        from fileroute.auth.settings import MicrosoftAuthConfig
+
+        resolved: MicrosoftAuthConfig = config if config is not None else MicrosoftAuthConfig()  # type: ignore[assignment]
+        return resolved.to_auth()
+
+    # ------------------------------------------------------------------
+    # Runtime helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def access_token(self) -> str:
+        """The raw Bearer access token string."""
+        return self._access_token
+
+
+__all__ = [
+    "MicrosoftAuth"
+]

fileroute/auth/settings.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Annotated
+
+from dotenv import find_dotenv
+from pydantic import AliasChoices, Field, SecretStr, field_validator, model_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+
+from fileroute.auth.google import (
+    DEFAULT_DRIVE_SCOPES,
+    GoogleAuth,
+)
+from fileroute.auth.microsoft import (
+    DEFAULT_MICROSOFT_GRAPH_SCOPES,
+    MicrosoftAuth,
+    normalize_microsoft_scopes,
+)
+
+
+class GoogleAuthMode(str, Enum):
+    ADC = "adc"
+    SERVICE_ACCOUNT = "service_account"
+    USER_OAUTH = "user_oauth"
+
+
+class MicrosoftAuthMode(str, Enum):
+    APP_ONLY = "app_only"
+    DELEGATED = "delegated"
+
+
+class GoogleAuthConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=find_dotenv(".env", usecwd=True),
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    auth_mode: GoogleAuthMode = Field(
+        default=GoogleAuthMode.ADC,
+        alias="GOOGLE_AUTH_MODE",
+    )
+    service_account_credentials: Path | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "GOOGLE_SERVICE_ACCOUNT_CREDENTIALS",
+            "GOOGLE_APPLICATION_CREDENTIALS",
+        ),
+    )
+    oauth_client_secrets: Path | None = Field(
+        default=None,
+        alias="GOOGLE_OAUTH_CREDENTIALS",
+    )
+    oauth_token_path: Path = Field(
+        default=".google/token.json",
+        alias="GOOGLE_OAUTH_TOKEN_PATH",
+    )
+    scopes: Annotated[list[str], NoDecode] = Field(
+        default_factory=lambda: list(DEFAULT_DRIVE_SCOPES),
+        alias="GOOGLE_SCOPES",
+    )
+    use_local_server: bool = Field(
+        default=True,
+        alias="GOOGLE_OAUTH_USE_LOCAL_SERVER",
+    )
+
+    @field_validator("scopes", mode="before")
+    @classmethod
+    def to_scope_list(cls, value: str | list[str] | tuple[str, ...] | None) -> list[str]:
+        if value is None:
+            return list(DEFAULT_DRIVE_SCOPES)
+        if isinstance(value, str):
+            parts = [part.strip() for part in value.split(",")]
+            return [part for part in parts if part] or list(DEFAULT_DRIVE_SCOPES)
+        return [scope for scope in value if scope]
+
+    @model_validator(mode="after")
+    def validate_for_mode(self) -> GoogleAuthConfig:
+        if (
+            self.auth_mode == GoogleAuthMode.SERVICE_ACCOUNT
+            and self.service_account_credentials is None
+        ):
+            raise ValueError(
+                "GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_SERVICE_ACCOUNT_CREDENTIALS is required for service_account mode."
+            )
+
+        if (
+            self.auth_mode == GoogleAuthMode.USER_OAUTH
+            and self.oauth_client_secrets is None
+        ):
+            raise ValueError(
+                "GOOGLE_OAUTH_CREDENTIALS is required for user_oauth mode."
+            )
+
+        return self
+
+    def to_auth(self) -> GoogleAuth:
+        """Return a :class:`~fileroute.auth.google.GoogleAuth` for this configuration."""
+        if self.auth_mode == GoogleAuthMode.ADC:
+            return GoogleAuth.from_adc(scopes=self.scopes)
+
+        elif self.auth_mode == GoogleAuthMode.SERVICE_ACCOUNT:
+            return GoogleAuth.from_service_account(
+                credentials_path=self.service_account_credentials,
+                scopes=self.scopes,
+            )
+
+        elif self.auth_mode == GoogleAuthMode.USER_OAUTH:
+            return GoogleAuth.from_user_oauth(
+                client_secrets_path=self.oauth_client_secrets,
+                token_path=self.oauth_token_path,
+                scopes=self.scopes
+            )
+        else:
+            if self.auth_mode:
+                raise ValueError(f"Unsupported Google auth mode: {self.auth_mode}")
+            else:
+                raise ValueError("GOOGLE_AUTH_MODE is required for Google authentication.")
+
+
+class MicrosoftAuthConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=find_dotenv(".env", usecwd=True),
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    auth_mode: MicrosoftAuthMode = Field(
+        default=MicrosoftAuthMode.APP_ONLY,
+        alias="SHAREPOINT_AUTH_MODE",
+    )
+    tenant_id: str | None = Field(default=None, alias="AZURE_TENANT_ID")
+    client_id: str | None = Field(default=None, alias="AZURE_CLIENT_ID")
+    client_secret: SecretStr | None = Field(
+        default=None,
+        alias="AZURE_CLIENT_SECRET",
+        validate_default=True,
+    )
+    host_url: str = Field(
+        default="norc.sharepoint.com",
+        validation_alias=AliasChoices("SHAREPOINT_HOST_URL", "AZURE_HOST_URL"),
+    )
+    scopes: Annotated[list[str], NoDecode] = Field(
+        default_factory=lambda: list(DEFAULT_MICROSOFT_GRAPH_SCOPES),
+        validation_alias=AliasChoices("SHAREPOINT_SCOPES", "AZURE_SCOPES"),
+    )
+
+    @field_validator("tenant_id", "client_id", mode="before")
+    @classmethod
+    def empty_string_to_none(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        return normalized or None
+
+    @field_validator("host_url", mode="before")
+    @classmethod
+    def normalize_host_url(cls, value: str | None) -> str:
+        if value is None:
+            return "norc.sharepoint.com"
+        normalized = value.strip()
+        return normalized or "norc.sharepoint.com"
+
+    @field_validator("scopes", mode="before")
+    @classmethod
+    def to_scope_list(
+        cls,
+        value: str | list[str] | tuple[str, ...] | None,
+    ) -> list[str]:
+        return normalize_microsoft_scopes(value)
+
+    @model_validator(mode="after")
+    def validate_for_mode(self) -> MicrosoftAuthConfig:
+        if self.tenant_id is None:
+            raise ValueError("AZURE_TENANT_ID is required for Microsoft authentication.")
+
+        if self.client_id is None:
+            raise ValueError("AZURE_CLIENT_ID is required for Microsoft authentication.")
+
+        if (
+            self.auth_mode == MicrosoftAuthMode.APP_ONLY
+            and self.client_secret is None
+        ):
+            raise ValueError("AZURE_CLIENT_SECRET is required for Microsoft app_only mode.")
+
+        return self
+
+    def to_auth(self) -> MicrosoftAuth:
+        """Return a :class:`~fileroute.auth.microsoft.MicrosoftAuth` for this configuration."""
+        if self.auth_mode == MicrosoftAuthMode.DELEGATED:
+            return MicrosoftAuth.from_delegated(
+                tenant_id=self.tenant_id,
+                client_id=self.client_id,
+                scopes=self.scopes,
+            )
+        elif self.auth_mode == MicrosoftAuthMode.APP_ONLY:
+            return MicrosoftAuth.from_app_only(
+                tenant_id=self.tenant_id,
+                client_id=self.client_id,
+                client_secret=self.client_secret.get_secret_value()
+                if self.client_secret is not None
+                else None,
+                scopes=self.scopes,
+            )
+        else:
+            if self.auth_mode:
+                raise ValueError(f"Unsupported Microsoft auth mode: {self.auth_mode}")
+            else:
+                raise ValueError("SHAREPOINT_AUTH_MODE or AZURE_AUTH_MODE is required for Microsoft authentication.")
+
+
+__all__ = [
+    "GoogleAuthConfig",
+    "GoogleAuthMode",
+    "MicrosoftAuthConfig",
+    "MicrosoftAuthMode",
+]

fileroute/auth/token_store.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from google.oauth2.credentials import Credentials as UserCredentials
+
+
+class JsonTokenStore:
+    """Persist Google authorized-user credentials as JSON."""
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path)
+
+    def load(self) -> UserCredentials | None:
+        if not self.path.exists():
+            return None
+        return UserCredentials.from_authorized_user_file(str(self.path))
+
+    def save(self, creds: UserCredentials) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(creds.to_json(), encoding="utf-8")
+
+
+__all__ = ["JsonTokenStore"]

fileroute/cli.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dotenv import find_dotenv, load_dotenv
+import typer
+
+from fileroute.commands import (
+    register_auth_commands,
+    register_descriptor_commands,
+    register_diagram_command,
+)
+
+load_dotenv(find_dotenv(usecwd=True))
+
+app = typer.Typer(
+    name="fileroute",
+    help="Shared drive utilities for SharePoint, Google Drive, and S3.",
+    rich_markup_mode="markdown",
+)
+clone_app = typer.Typer(
+    help="Clone descriptor state for new local variants.", rich_markup_mode="markdown"
+)
+auth_app = typer.Typer(help="Authentication helpers.", rich_markup_mode="markdown")
+auth_login_app = typer.Typer(
+    help="Interactive login commands.", rich_markup_mode="markdown"
+)
+app.add_typer(auth_app, name="auth")
+app.add_typer(clone_app, name="clone")
+auth_app.add_typer(auth_login_app, name="login")
+
+register_descriptor_commands(app, clone_app)
+register_diagram_command(app)
+register_auth_commands(auth_app, auth_login_app)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

fileroute/clients/__init__.py

@@ -0,0 +1,24 @@
+"""Built-in clients selected by the descriptor's ServiceType enum."""
+
+from fileroute.models import ServiceType
+from fileroute.clients.base import BaseClient
+
+
+def get_provider(service_type: ServiceType) -> type[BaseClient]:
+    """Select a client class without constructing it or authenticating."""
+    if service_type is ServiceType.GOOGLE_DRIVE:
+        from .googledrive import GoogleDriveClient
+
+        return GoogleDriveClient
+    if service_type is ServiceType.SHAREPOINT:
+        from .sharepoint import SharepointClient
+
+        return SharepointClient
+    if service_type is ServiceType.S3:
+        from .s3 import S3Client
+
+        return S3Client
+    raise ValueError(f"Expected a resolved ServiceType, got {service_type!r}")
+
+
+__all__ = ["get_provider"]