ms365-toolkit 0.1.0__py3-none-any.whl

ms365_toolkit/__init__.py

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

ms365_toolkit/auth/__init__.py

@@ -0,0 +1,11 @@
+from ms365_toolkit.auth.credentials import CredentialStore
+from ms365_toolkit.auth.device_code import DeviceCodePrompt, authenticate_device_code
+from ms365_toolkit.auth.tokens import TokenBundle, TokenManager
+
+__all__ = [
+    "CredentialStore",
+    "DeviceCodePrompt",
+    "TokenBundle",
+    "TokenManager",
+    "authenticate_device_code",
+]

ms365_toolkit/auth/credentials.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+import keyring
+import msal  # type: ignore[import-untyped]
+from keyring.errors import PasswordDeleteError, PasswordSetError
+
+from ms365_toolkit.models.enums import (
+    DELEGATED_READ_SCOPES,
+    DELEGATED_WRITE_SCOPES,
+    READ_SCOPES,
+    WRITE_SCOPES,
+)
+
+if TYPE_CHECKING:
+    from ms365_toolkit.config.loader import ToolkitConfig
+
+SERVICE_NAME = "ms365-toolkit"
+READ_CACHE_KEY = "ms365-read-token-{profile}"
+WRITE_CACHE_KEY = "ms365-write-token-{profile}"
+READ_ENV_KEY = "MS365_READ_TOKEN_CACHE_{profile}"
+WRITE_ENV_KEY = "MS365_WRITE_TOKEN_CACHE_{profile}"
+
+
+@dataclass(frozen=True)
+class CredentialStore:
+    profile: str
+    keyring_backend: Any = keyring
+
+    def load_cache(
+        self,
+        *,
+        kind: str,
+        explicit_value: str | None = None,
+        allow_env: bool = True,
+    ) -> msal.SerializableTokenCache:
+        cache = msal.SerializableTokenCache()
+        raw_value = self._resolve_raw_cache(
+            kind=kind,
+            explicit_value=explicit_value,
+            allow_env=allow_env,
+        )
+        if raw_value:
+            cache.deserialize(raw_value)
+        return cache
+
+    def save_cache(
+        self,
+        *,
+        kind: str,
+        cache: msal.SerializableTokenCache,
+        allow_env_write: bool = False,
+    ) -> None:
+        serialized = cache.serialize()
+        cache_key = self._cache_key(kind)
+        try:
+            self.keyring_backend.set_password(
+                SERVICE_NAME,
+                cache_key,
+                serialized,
+            )
+        except PasswordSetError:
+            with suppress(PasswordDeleteError):
+                self.keyring_backend.delete_password(SERVICE_NAME, cache_key)
+            self.keyring_backend.set_password(
+                SERVICE_NAME,
+                cache_key,
+                serialized,
+            )
+        if kind != "write" or not allow_env_write:
+            return
+        os.environ[self._env_key(kind)] = serialized
+
+    def delete_cache(self, *, kind: str) -> None:
+        with suppress(PasswordDeleteError):
+            self.keyring_backend.delete_password(SERVICE_NAME, self._cache_key(kind))
+        os.environ.pop(self._env_key(kind), None)
+
+    def scopes_for(self, config: ToolkitConfig, *, write: bool) -> frozenset[str]:
+        if config.user.endpoint == "users":
+            return DELEGATED_WRITE_SCOPES if write else DELEGATED_READ_SCOPES
+        return WRITE_SCOPES if write else READ_SCOPES
+
+    def _resolve_raw_cache(
+        self,
+        *,
+        kind: str,
+        explicit_value: str | None,
+        allow_env: bool,
+    ) -> str | None:
+        if explicit_value:
+            return explicit_value
+        value = cast(
+            "str | None",
+            self.keyring_backend.get_password(SERVICE_NAME, self._cache_key(kind)),
+        )
+        if value:
+            return value
+        if allow_env:
+            return os.environ.get(self._env_key(kind))
+        return None
+
+    def _cache_key(self, kind: str) -> str:
+        if kind == "read":
+            return READ_CACHE_KEY.format(profile=self.profile)
+        if kind == "write":
+            return WRITE_CACHE_KEY.format(profile=self.profile)
+        raise ValueError(f"unsupported cache kind: {kind}")
+
+    def _env_key(self, kind: str) -> str:
+        if kind == "read":
+            return READ_ENV_KEY.format(profile=_env_profile(self.profile))
+        if kind == "write":
+            return WRITE_ENV_KEY.format(profile=_env_profile(self.profile))
+        raise ValueError(f"unsupported cache kind: {kind}")
+
+
+def _env_profile(profile: str) -> str:
+    return profile.upper().replace("-", "_")

ms365_toolkit/auth/device_code.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from ms365_toolkit.client.exceptions import AuthenticationError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import msal  # type: ignore[import-untyped]
+
+    from ms365_toolkit.auth.credentials import CredentialStore
+    from ms365_toolkit.config.loader import ToolkitConfig
+
+
+@dataclass(frozen=True)
+class DeviceCodePrompt:
+    verification_uri: str
+    user_code: str
+    message: str
+
+
+def authenticate_device_code(
+    *,
+    config: ToolkitConfig,
+    credential_store: CredentialStore,
+    write: bool,
+    presenter: Callable[[DeviceCodePrompt], None],
+    app_factory: Callable[[msal.SerializableTokenCache], Any],
+    allow_env_write: bool = False,
+) -> dict[str, Any]:
+    cache = credential_store.load_cache(kind="write" if write else "read", allow_env=not write)
+    scopes = credential_store.scopes_for(config, write=write)
+    app = app_factory(cache)
+    flow = app.initiate_device_flow(scopes=list(scopes))
+    verification_uri = flow.get("verification_uri")
+    user_code = flow.get("user_code")
+    message = flow.get("message")
+    if not all(
+        isinstance(value, str) and value for value in (verification_uri, user_code, message)
+    ):
+        raise AuthenticationError("device code flow did not return verification details")
+    presenter(
+        DeviceCodePrompt(
+            verification_uri=verification_uri,
+            user_code=user_code,
+            message=message,
+        )
+    )
+    result = app.acquire_token_by_device_flow(flow)
+    access_token = result.get("access_token") if isinstance(result, dict) else None
+    if not isinstance(access_token, str) or not access_token:
+        raise AuthenticationError("device code authentication failed")
+    credential_store.save_cache(
+        kind="write" if write else "read",
+        cache=cache,
+        allow_env_write=allow_env_write,
+    )
+    return cast("dict[str, Any]", result)

ms365_toolkit/auth/tokens.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+import jwt
+
+from ms365_toolkit.client.exceptions import AuthenticationError, InsufficientScopesError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import msal  # type: ignore[import-untyped]
+
+    from ms365_toolkit.auth.credentials import CredentialStore
+    from ms365_toolkit.config.loader import ToolkitConfig
+
+
+@dataclass(frozen=True)
+class TokenBundle:
+    access_token: str
+    scopes: frozenset[str]
+    expires_at: datetime
+
+
+class TokenManager:
+    def __init__(
+        self,
+        *,
+        config: ToolkitConfig,
+        credential_store: CredentialStore,
+        app_factory: Callable[[msal.SerializableTokenCache], Any],
+        auth_callback: (
+            Callable[[frozenset[str], msal.SerializableTokenCache, str], dict[str, Any]] | None
+        ) = None,
+    ) -> None:
+        self.config = config
+        self.credential_store = credential_store
+        self.app_factory = app_factory
+        self.auth_callback = auth_callback
+
+    def get_access_token(self, *, write: bool = False) -> TokenBundle:
+        kind = "write" if write else "read"
+        cache = self.credential_store.load_cache(kind=kind, allow_env=not write)
+        app = self.app_factory(cache)
+        scopes = self.credential_store.scopes_for(self.config, write=write)
+        result = self._acquire_token(app, scopes, cache, kind)
+        access_token = result.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise AuthenticationError(f"missing access token for {kind} scopes")
+        if _is_expiring(access_token):
+            result = self._interactive_refresh(scopes, cache, kind)
+            access_token = result.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise AuthenticationError(f"missing refreshed access token for {kind} scopes")
+        token_scopes = _token_scopes(result, access_token)
+        normalized_scopes = frozenset(scope.lower() for scope in scopes)
+        if not normalized_scopes.issubset(token_scopes):
+            raise InsufficientScopesError(scopes, token_scopes)
+        self.credential_store.save_cache(kind=kind, cache=cache, allow_env_write=False)
+        return TokenBundle(
+            access_token=access_token,
+            scopes=token_scopes,
+            expires_at=_token_expiry(access_token),
+        )
+
+    def _acquire_token(
+        self,
+        app: Any,
+        scopes: frozenset[str],
+        cache: msal.SerializableTokenCache,
+        kind: str,
+    ) -> dict[str, Any]:
+        accounts = app.get_accounts()
+        account = accounts[0] if accounts else None
+        result = app.acquire_token_silent(list(scopes), account=account)
+        if isinstance(result, dict) and result.get("access_token"):
+            return result
+        return self._interactive_refresh(scopes, cache, kind)
+
+    def _interactive_refresh(
+        self,
+        scopes: frozenset[str],
+        cache: msal.SerializableTokenCache,
+        kind: str,
+    ) -> dict[str, Any]:
+        if self.auth_callback is None:
+            raise AuthenticationError(f"interactive authentication required for {kind} scopes")
+        result = self.auth_callback(scopes, cache, kind)
+        if not isinstance(result, dict):
+            raise AuthenticationError("authentication callback returned invalid result")
+        return result
+
+
+def _token_expiry(access_token: str) -> datetime:
+    payload = jwt.decode(access_token, options={"verify_signature": False, "verify_aud": False})
+    exp = payload.get("exp")
+    if not isinstance(exp, int):
+        raise AuthenticationError("token does not contain integer exp claim")
+    return datetime.fromtimestamp(exp, tz=UTC)
+
+
+def _is_expiring(access_token: str, *, grace_period: timedelta = timedelta(minutes=5)) -> bool:
+    return _token_expiry(access_token) <= datetime.now(UTC) + grace_period
+
+
+def _token_scopes(result: dict[str, Any], access_token: str) -> frozenset[str]:
+    scope_string = result.get("scope") or result.get("scopes") or result.get("scp")
+    if isinstance(scope_string, str) and scope_string.strip():
+        return frozenset(scope.lower() for scope in scope_string.split())
+    payload = jwt.decode(access_token, options={"verify_signature": False, "verify_aud": False})
+    token_scope_string = payload.get("scp")
+    if not isinstance(token_scope_string, str):
+        raise AuthenticationError("token does not contain scopes")
+    return frozenset(scope.lower() for scope in token_scope_string.split())

ms365_toolkit/cli/__init__.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+from typing import TYPE_CHECKING
+
+from ms365_toolkit.cli.auth import login_command, revoke_write_command, status_command
+from ms365_toolkit.cli.inbox import inbox_command
+from ms365_toolkit.cli.labeling import (
+    export_label_candidates_command,
+    label_thread_command,
+    review_label_candidates_command,
+)
+from ms365_toolkit.cli.labeling_web import launch_label_ui_command
+from ms365_toolkit.cli.read_tools import (
+    download_email_attachments_command,
+    list_events_command,
+    morning_brief_command,
+    read_email_command,
+    search_emails_command,
+    search_local_mail_index_command,
+    sync_mail_index_command,
+    triage_inbox_command,
+)
+from ms365_toolkit.config.loader import load_config
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "handler"):
+        parser.print_help()
+        return 1
+    if args.command == "revoke-write":
+        return int(args.handler(args))
+    config = load_config(profile=args.profile)
+    return int(args.handler(args, config))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ms365-toolkit")
+    parser.add_argument("--profile", default="default")
+    subparsers = parser.add_subparsers(dest="command")
+
+    auth_parser = subparsers.add_parser("auth")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command")
+
+    login_parser = auth_subparsers.add_parser("login")
+    login_parser.add_argument("--write", action="store_true")
+    login_parser.add_argument("--insecure-env-write", action="store_true")
+    login_parser.set_defaults(handler=login_command)
+
+    status_parser = auth_subparsers.add_parser("status")
+    status_parser.set_defaults(handler=status_command)
+
+    revoke_parser = auth_subparsers.add_parser("revoke-write")
+    revoke_parser.set_defaults(handler=revoke_write_command, command="revoke-write")
+
+    inbox_parser = subparsers.add_parser("inbox")
+    inbox_parser.add_argument("--top", type=int, default=10)
+    inbox_parser.add_argument("--filter", choices=("focused", "all"), default="all")
+    inbox_parser.set_defaults(handler=inbox_command)
+
+    search_parser = subparsers.add_parser("search-emails")
+    search_parser.add_argument("query")
+    search_parser.add_argument("--top", type=int, default=10)
+    search_parser.add_argument("--filter", choices=("focused", "all"), default="all")
+    search_parser.set_defaults(handler=search_emails_command)
+
+    sync_index_parser = subparsers.add_parser("sync-mail-index")
+    sync_index_parser.add_argument("--batch-size", type=int, default=100)
+    sync_index_parser.add_argument("--max-pages", type=int, default=10)
+    sync_index_parser.set_defaults(handler=sync_mail_index_command)
+
+    search_local_parser = subparsers.add_parser("search-local-mail")
+    search_local_parser.add_argument("query")
+    search_local_parser.add_argument("--top", type=int, default=10)
+    search_local_parser.set_defaults(handler=search_local_mail_index_command)
+
+    export_labels_parser = subparsers.add_parser("export-label-candidates")
+    export_labels_parser.add_argument("--top", type=int, default=20)
+    export_labels_parser.add_argument("--sync-index", action="store_true")
+    export_labels_parser.add_argument("--max-pages", type=int, default=5)
+    export_labels_parser.set_defaults(handler=export_label_candidates_command)
+
+    review_labels_parser = subparsers.add_parser("review-label-candidates")
+    review_labels_parser.add_argument("--top", type=int, default=10)
+    review_labels_parser.add_argument(
+        "--status",
+        choices=("unlabeled", "labeled", "all"),
+        default="unlabeled",
+    )
+    review_labels_parser.add_argument("--thread-id")
+    review_labels_parser.set_defaults(handler=review_label_candidates_command)
+
+    label_ui_parser = subparsers.add_parser("label-ui")
+    label_ui_parser.add_argument("--host", default="127.0.0.1")
+    label_ui_parser.add_argument("--port", type=int, default=8765)
+    label_ui_parser.add_argument("--no-open", action="store_true")
+    label_ui_parser.set_defaults(handler=launch_label_ui_command)
+
+    label_thread_parser = subparsers.add_parser("label-thread")
+    label_thread_parser.add_argument("thread_id")
+    label_thread_parser.add_argument(
+        "--thread-class",
+        required=True,
+        choices=(
+            "approval_request",
+            "decision_request",
+            "incident_or_risk",
+            "contract_or_renewal",
+            "strategic_update",
+            "status_update",
+            "fyi_noise",
+        ),
+    )
+    label_thread_parser.add_argument(
+        "--action-needed",
+        required=True,
+        choices=("yes", "no", "unclear"),
+    )
+    label_thread_parser.add_argument(
+        "--urgency",
+        required=True,
+        choices=("high", "medium", "low"),
+    )
+    label_thread_parser.add_argument(
+        "--acted-by-you",
+        required=True,
+        choices=("replied", "forwarded", "ignored", "archived", "unknown"),
+    )
+    label_thread_parser.add_argument("--confidence", required=True, type=float)
+    label_thread_parser.add_argument("--notes")
+    label_thread_parser.set_defaults(handler=label_thread_command)
+
+    triage_parser = subparsers.add_parser("triage-inbox")
+    triage_parser.add_argument("--top", type=int, default=15)
+    triage_parser.add_argument("--limit", type=int, default=5)
+    triage_parser.add_argument("--sync-index", action="store_true")
+    triage_parser.add_argument("--max-pages", type=int, default=5)
+    triage_parser.set_defaults(handler=triage_inbox_command)
+
+    read_email_parser = subparsers.add_parser("read-email")
+    read_email_parser.add_argument("message_id")
+    read_email_parser.set_defaults(handler=read_email_command)
+
+    download_attachments_parser = subparsers.add_parser("download-email-attachments")
+    download_attachments_parser.add_argument("message_id")
+    download_attachments_parser.add_argument("--output-dir", default=".")
+    download_attachments_parser.set_defaults(handler=download_email_attachments_command)
+
+    list_events_parser = subparsers.add_parser("list-events")
+    list_events_parser.add_argument("--hours", type=int, default=8)
+    list_events_parser.set_defaults(handler=list_events_command)
+
+    morning_brief_parser = subparsers.add_parser("morning-brief")
+    morning_brief_parser.add_argument("--top", type=int, default=10)
+    morning_brief_parser.set_defaults(handler=morning_brief_command)
+
+    return parser

ms365_toolkit/cli/auth.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import msal  # type: ignore[import-untyped]
+
+from ms365_toolkit.auth.credentials import CredentialStore
+from ms365_toolkit.auth.device_code import DeviceCodePrompt, authenticate_device_code
+from ms365_toolkit.auth.tokens import TokenBundle, TokenManager
+from ms365_toolkit.client.exceptions import AuthenticationError
+from ms365_toolkit.config.loader import ToolkitConfig
+
+if TYPE_CHECKING:
+    from argparse import Namespace
+
+    from ms365_toolkit.config.loader import ToolkitConfig
+
+
+AUTHORITY_TEMPLATE = "https://login.microsoftonline.com/{tenant_id}"
+
+
+@dataclass(frozen=True)
+class AuthStatus:
+    logged_in: bool
+    scopes: tuple[str, ...]
+    expires_at: str | None
+
+
+def login_command(args: Namespace, config: ToolkitConfig) -> int:
+    store = CredentialStore(profile=args.profile)
+    authenticate_device_code(
+        config=config,
+        credential_store=store,
+        write=bool(args.write),
+        presenter=_print_device_code_prompt,
+        app_factory=lambda cache: build_public_client_application(config, cache),
+        allow_env_write=bool(args.insecure_env_write),
+    )
+    print(f"Stored {'write' if args.write else 'read'} token cache for profile {args.profile}.")
+    return 0
+
+
+def status_command(args: Namespace, config: ToolkitConfig) -> int:
+    status = get_auth_status(profile=args.profile, config=config)
+    if not status.logged_in:
+        print(f"Profile {args.profile}: not logged in")
+        return 1
+    scopes = ", ".join(status.scopes)
+    print(f"Profile {args.profile}: logged in")
+    print(f"Scopes: {scopes}")
+    if status.expires_at is not None:
+        print(f"Expires: {status.expires_at}")
+    return 0
+
+
+def revoke_write_command(args: Namespace) -> int:
+    store = CredentialStore(profile=args.profile)
+    store.delete_cache(kind="write")
+    print(f"Removed write token cache for profile {args.profile}.")
+    return 0
+
+
+def get_auth_status(profile: str, config: ToolkitConfig) -> AuthStatus:
+    store = CredentialStore(profile=profile)
+    try:
+        bundle = _load_bundle(config=config, store=store)
+    except AuthenticationError:
+        return AuthStatus(logged_in=False, scopes=(), expires_at=None)
+    return AuthStatus(
+        logged_in=True,
+        scopes=tuple(sorted(bundle.scopes)),
+        expires_at=bundle.expires_at.isoformat(),
+    )
+
+
+def _load_bundle(config: ToolkitConfig, store: CredentialStore) -> TokenBundle:
+    manager = TokenManager(
+        config=config,
+        credential_store=store,
+        app_factory=lambda cache: build_public_client_application(config, cache),
+    )
+    return manager.get_access_token(write=False)
+
+
+def build_public_client_application(
+    config: ToolkitConfig,
+    cache: msal.SerializableTokenCache,
+) -> msal.PublicClientApplication:
+    return msal.PublicClientApplication(
+        client_id=config.auth.client_id,
+        authority=AUTHORITY_TEMPLATE.format(tenant_id=config.auth.tenant_id),
+        token_cache=cache,
+    )
+
+
+def _print_device_code_prompt(prompt: DeviceCodePrompt) -> None:
+    print(prompt.message)
+    print(f"Verification URL: {prompt.verification_uri}")
+    print(f"User code: {prompt.user_code}")

ms365_toolkit/cli/inbox.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ms365_toolkit.cli.read_common import build_read_clients
+
+if TYPE_CHECKING:
+    from argparse import Namespace
+
+    from ms365_toolkit.config.loader import ToolkitConfig
+
+
+def inbox_command(args: Namespace, config: ToolkitConfig) -> int:
+    email_client, _ = build_read_clients(config, args.profile)
+    mailbox_filter = None if args.filter == "all" else args.filter
+    messages = email_client.list_inbox(mailbox_filter=mailbox_filter, top=args.top, skip=0)
+    if not messages:
+        print("No messages found.")
+        return 0
+    for message in messages:
+        print(
+            f"{message.received_at.isoformat()} {message.id} "
+            f"{message.conversation_id} {message.sender} {message.subject}"
+        )
+    return 0