teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/services/tenant.py

@@ -0,0 +1,684 @@
+"""Tenant detection, matching, verification, switching, and listing service.
+
+Implements the detect-verify-switch approach: check that the Teams desktop
+app is signed into the correct Azure AD tenant before proceeding with
+transcript download.  If the tenant does not match, raises
+``TenantSwitchNeededError`` so the pipeline can kill and relaunch Teams
+on the correct tenant.  If the requested tenant is not in the available
+list at all, exits with code 6 (``TENANT_NOT_FOUND``).
+
+Also provides ``--list-tenants`` support: ``run_list_tenants()`` connects
+to Teams via CDP, discovers available tenants, and prints a formatted
+table or JSON array.
+
+Public API:
+    detect_current_tenant(browser) -> dict | None
+    list_available_tenants(browser) -> list[dict]
+    match_tenant(domain, tenants) -> dict | None       (pure function)
+    resolve_requested_tenant(browser, tenant, logger, format_json) -> TenantVerification
+    pick_detection_target(targets) -> str               (pure function)
+    format_tenants_text(tenants, current) -> str        (pure function)
+    format_tenants_json(tenants, current) -> str        (pure function)
+    ensure_tenant(browser, config, logger) -> TenantVerification | None
+    run_list_tenants(port, ...) -> None                 (async orchestrator)
+    TenantSwitchNeededError                             (exception)
+
+Schema version: 1.2.0
+Created: 2026-04-26
+Updated: 2026-04-26
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import typing
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.domain.models import MeetingConfig
+    from teams_transcripts.infrastructure.logging import Logger
+    from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+    from teams_transcripts.ports.browser import BrowserPort
+
+from teams_transcripts.infrastructure.errors import (
+    ERROR_TENANT_NOT_FOUND,
+    EXIT_TENANT_NOT_FOUND,
+    exit_error,
+)
+
+# ---------------------------------------------------------------------------
+# Exception for tenant switching
+# ---------------------------------------------------------------------------
+
+
+class TenantSwitchNeededError(Exception):
+    """Raised when the current tenant does not match the requested tenant.
+
+    The pipeline should catch this, kill Teams, relaunch with the
+    ``tenant_id`` in the URL, and re-verify.
+
+    Attributes:
+        tenant_id: Azure AD tenant ID for the target tenant.
+        domain: Display domain for the target tenant.
+    """
+
+    def __init__(self, tenant_id: str, domain: str) -> None:
+        self.tenant_id = tenant_id
+        self.domain = domain
+        super().__init__(f"Switch to tenant {domain} ({tenant_id})")
+
+
+class TenantVerification(typing.NamedTuple):
+    """Canonical tenant details after verification."""
+
+    tenant_id: str
+    domain: str
+
+
+# ---------------------------------------------------------------------------
+# JavaScript expressions
+# ---------------------------------------------------------------------------
+
+# Extract tenantId and tenantName from the clientStartupConfiguration
+# element embedded in the Teams page DOM.
+_JS_DETECT_TENANT = """\
+(function() {
+    try {
+        var el = document.getElementById('clientStartupConfiguration');
+        if (!el) return null;
+        var cfg = JSON.parse(el.textContent);
+        if (!cfg.tenantId) return null;
+        return JSON.stringify({tenantId: cfg.tenantId, tenantName: cfg.tenantName || ''});
+    } catch(e) {
+        return null;
+    }
+})()
+"""
+
+# Fallback: extract tenant display name from the page title.
+# Title format: "... | TenantName | UPN | Microsoft Teams"
+# Returns just the tenant display name string, or null.
+_JS_DETECT_TENANT_FROM_TITLE = """\
+(function() {
+    try {
+        var title = document.title;
+        if (!title || title.indexOf('Microsoft Teams') < 0) return null;
+        var parts = title.split(' | ');
+        if (parts.length < 3) return null;
+        if (parts[parts.length - 1].trim() !== 'Microsoft Teams') return null;
+        var tenantName = parts[parts.length - 3].trim();
+        if (!tenantName) return null;
+        return tenantName;
+    } catch(e) {
+        return null;
+    }
+})()
+"""
+
+# Acquire a token for the Teams API, then fetch the tenants list.
+# Returns a JSON array of tenant objects, or null on failure.
+#
+# This is a single async IIFE that acquires a token via the WAM bridge
+# and fetches the /users/tenants endpoint in one expression.  Must be
+# evaluated with awaitPromise: true in CDP Runtime.evaluate.
+_JS_LIST_TENANTS = """\
+(async function() {
+    try {
+        var wamResult = await window.getWamAccessToken(
+            'https://api.spaces.skype.com', '', ''
+        );
+        if (!wamResult || !wamResult.success || !wamResult.token) return null;
+        var resp = await fetch(
+            'https://teams.microsoft.com/api/mt/emea/beta/users/tenants',
+            {headers: {'Authorization': 'Bearer ' + wamResult.token}}
+        );
+        if (!resp.ok) return null;
+        var data = await resp.json();
+        return JSON.stringify(data);
+    } catch(e) {
+        return null;
+    }
+})()
+"""
+
+# Fallback: read the tenants list from localStorage.
+# Teams caches it under tmp.auth.v1.<userId>.Tenants.Tenants.
+# Multiple keys may exist (one per account); we pick the one with the
+# most tenant entries that have non-empty tenantName fields.
+# Returns a JSON array of tenant objects, or null.
+_JS_LIST_TENANTS_FROM_STORAGE = """\
+(function() {
+    try {
+        var best = null;
+        var bestLen = 0;
+        for (var i = 0; i < localStorage.length; i++) {
+            var key = localStorage.key(i);
+            if (key && key.indexOf('.Tenants.Tenants') > 0 &&
+                key.indexOf('tmp.auth.v1.') === 0) {
+                var raw = localStorage.getItem(key);
+                if (!raw) continue;
+                var parsed = JSON.parse(raw);
+                var items = parsed.item || parsed;
+                if (!Array.isArray(items)) continue;
+                var named = items.filter(function(t) { return t.tenantName; });
+                if (named.length > bestLen) {
+                    best = items;
+                    bestLen = named.length;
+                }
+            }
+        }
+        return best && best.length > 0 ? JSON.stringify(best) : null;
+    } catch(e) {
+        return null;
+    }
+})()
+"""
+
+
+# ---------------------------------------------------------------------------
+# detect_current_tenant
+# ---------------------------------------------------------------------------
+
+
+async def detect_current_tenant(browser: BrowserPort) -> dict | None:
+    """Detect the current tenant from the Teams page DOM.
+
+    Tries two methods in order:
+
+    1. Read ``clientStartupConfiguration`` for ``tenantId`` (M365 Copilot
+       wrapper mode).
+    2. Parse the page title for the tenant display name (direct Teams mode).
+       Title format: ``"... | TenantName | UPN | Microsoft Teams"``.
+
+    Args:
+        browser: Connected browser adapter (already attached to a
+            Teams page target).
+
+    Returns:
+        A dict with at least ``tenantId`` or ``tenantName`` keys,
+        or ``None`` if detection fails by both methods.
+    """
+    # Method 1: clientStartupConfiguration element
+    raw = await browser.evaluate(_JS_DETECT_TENANT)
+    if isinstance(raw, str):
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            data = None
+        if isinstance(data, dict) and data.get("tenantId"):
+            return data
+
+    # Method 2: page title parsing
+    title_name = await browser.evaluate(_JS_DETECT_TENANT_FROM_TITLE)
+    if isinstance(title_name, str) and title_name:
+        return {"tenantId": "", "tenantName": title_name}
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# list_available_tenants
+# ---------------------------------------------------------------------------
+
+
+async def list_available_tenants(browser: BrowserPort) -> list[dict]:
+    """List all tenants the current user belongs to.
+
+    Tries two methods in order:
+
+    1. Acquire a ``api.spaces.skype.com`` token via WAM and call the
+       Teams ``/users/tenants`` API (M365 Copilot wrapper mode).
+    2. Read the cached tenants list from ``localStorage``
+       (``tmp.auth.v1.<userId>.Tenants.Tenants``) (direct Teams mode).
+
+    Args:
+        browser: Connected browser adapter.
+
+    Returns:
+        A list of tenant dicts (each with ``tenantId``, ``tenantName``,
+        ``tenantPrimaryDomainName``), or an empty list on failure.
+    """
+    # Method 1: WAM token + API call (async, needs awaitPromise)
+    resp = await browser.send_command(
+        "Runtime.evaluate",
+        {"expression": _JS_LIST_TENANTS, "awaitPromise": True},
+    )
+    raw = resp.get("result", {}).get("result", {}).get("value")
+    tenants = _parse_tenants_json(raw)
+    if tenants:
+        return tenants
+
+    # Method 2: localStorage cache (sync JS)
+    raw_storage = await browser.evaluate(_JS_LIST_TENANTS_FROM_STORAGE)
+    tenants = _parse_tenants_json(raw_storage)
+    if tenants:
+        return tenants
+
+    return []
+
+
+def _parse_tenants_json(raw: object) -> list[dict] | None:
+    """Parse a JSON string into a list of tenant dicts, or return None."""
+    if raw is None or not isinstance(raw, str):
+        return None
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if not isinstance(data, list):
+        return None
+    return data or None
+
+
+# ---------------------------------------------------------------------------
+# pick_detection_target (pure function)
+# ---------------------------------------------------------------------------
+
+
+def pick_detection_target(targets: list[dict]) -> str:
+    """Choose the best CDP target for tenant detection.
+
+    Prefers a target with a descriptive title (e.g.
+    ``"Chat | ... | TenantName | ..."``) over a generic
+    ``"Microsoft Teams"`` shell page.  Descriptive titles are
+    identified by containing at least two ``" | "`` separators.
+
+    Args:
+        targets: Non-empty list of Teams page target dicts.
+
+    Returns:
+        The ``id`` of the best target for tenant detection.
+    """
+    for t in targets:
+        title = t.get("title", "")
+        if title.count(" | ") >= 2:
+            return t["id"]
+    return targets[0]["id"]
+
+
+# ---------------------------------------------------------------------------
+# match_tenant (pure function)
+# ---------------------------------------------------------------------------
+
+
+def match_tenant(domain: str, tenants: list[dict]) -> dict | None:
+    """Find a tenant matching the given domain name.
+
+    Performs case-insensitive matching against both ``tenantName`` and
+    ``tenantPrimaryDomainName`` fields.
+
+    Args:
+        domain: Domain name to match (e.g. ``"abccorp.com"``,
+            ``"contoso.onmicrosoft.com"``).
+        tenants: List of tenant dicts from :func:`list_available_tenants`.
+
+    Returns:
+        The matching tenant dict, or ``None`` if no match is found.
+    """
+    needle = domain.lower()
+    for t in tenants:
+        name = t.get("tenantName", "")
+        primary = t.get("tenantPrimaryDomainName", "")
+        if needle == name.lower() or needle == primary.lower():
+            return t
+    return None
+
+
+def _tenant_domain(tenant: dict, fallback: str) -> str:
+    """Return the display domain/name for a tenant entry."""
+    return tenant.get("tenantPrimaryDomainName") or tenant.get("tenantName", fallback)
+
+
+async def resolve_requested_tenant(
+    browser: BrowserPort,
+    tenant: str,
+    logger: Logger,
+    *,
+    format_json: bool = False,
+) -> TenantVerification:
+    """Resolve a requested tenant name/domain to canonical tenant details.
+
+    Args:
+        browser: Connected browser adapter.
+        tenant: Tenant name or primary domain supplied by the user.
+        logger: Logger instance for diagnostic output.
+        format_json: Whether errors should be emitted as JSON.
+
+    Returns:
+        Canonical tenant ID and display domain.
+
+    Raises:
+        SystemExit: If the tenant list cannot be read, no matching tenant is
+            available, or the matching entry lacks a tenant ID.
+    """
+    tenants = await list_available_tenants(browser)
+    matched = match_tenant(tenant, tenants)
+    if matched is None:
+        available = [_tenant_domain(t, "?") for t in tenants]
+        available_str = ", ".join(available) if available else "(none discovered)"
+        exit_error(
+            EXIT_TENANT_NOT_FOUND,
+            ERROR_TENANT_NOT_FOUND,
+            f"Tenant '{tenant}' not found. Available tenants: {available_str}",
+            format_json=format_json,
+        )
+        raise AssertionError("unreachable: exit_error returned")
+
+    tenant_id = matched.get("tenantId", "")
+    domain = _tenant_domain(matched, tenant)
+    if not tenant_id:
+        exit_error(
+            EXIT_TENANT_NOT_FOUND,
+            ERROR_TENANT_NOT_FOUND,
+            f"Tenant '{tenant}' matched '{domain}' but did not include a tenant ID.",
+            format_json=format_json,
+        )
+        raise AssertionError("unreachable: exit_error returned")
+
+    logger.log("tenant", f"Tenant resolved: {domain} ({tenant_id[:8]}...)")
+    return TenantVerification(tenant_id=tenant_id, domain=domain)
+
+
+# ---------------------------------------------------------------------------
+# ensure_tenant
+# ---------------------------------------------------------------------------
+
+
+async def ensure_tenant(
+    browser: BrowserPort,
+    config: MeetingConfig,
+    logger: Logger,
+) -> TenantVerification | None:
+    """Verify that Teams is on the correct tenant.
+
+    If ``config.tenant`` is ``None``, this function does nothing and
+    returns ``None``.
+
+    If the current tenant matches the requested tenant, returns canonical
+    tenant details containing the Azure AD tenant ID and primary domain.
+
+    If there is a mismatch and the requested tenant IS in the
+    available list, raises ``TenantSwitchNeededError`` with the
+    target tenant ID and domain.  The pipeline catches this and
+    handles the kill+relaunch.
+
+    If the requested tenant is NOT in the available list, calls
+    ``exit_error()`` with exit code 6 (``TENANT_NOT_FOUND``).
+
+    Args:
+        browser: Connected browser adapter.
+        config: Pipeline configuration (with ``tenant`` and
+            ``format_json`` fields).
+        logger: Logger instance for diagnostic output.
+
+    Returns:
+        Tenant verification details, or ``None`` when ``config.tenant`` is
+        not set.
+
+    Raises:
+        TenantSwitchNeededError: When the current tenant does not
+            match and the requested tenant is in the available list.
+    """
+    if config.tenant is None:
+        return None
+
+    format_json = config.format_json
+
+    # Step 1: detect current tenant
+    logger.log("tenant", f"Verifying tenant: {config.tenant}")
+    current = await detect_current_tenant(browser)
+    if current is None:
+        exit_error(
+            EXIT_TENANT_NOT_FOUND,
+            ERROR_TENANT_NOT_FOUND,
+            "Could not detect current tenant. The Teams page DOM may have changed.",
+            format_json=format_json,
+        )
+
+    # Step 2: list available tenants
+    tenants = await list_available_tenants(browser)
+
+    # Step 3: resolve the current tenant's identity.
+    # Detection may return a tenantId (from clientStartupConfiguration)
+    # or just a tenantName (from page title parsing).  If we only have
+    # a display name, look it up in the tenants list to get the ID.
+    current_id = current.get("tenantId", "")
+    current_name = current.get("tenantName", "")
+
+    if not current_id and current_name and tenants:
+        # Title-based detection: match display name against tenants list
+        name_lower = current_name.lower()
+        for t in tenants:
+            if t.get("tenantName", "").lower() == name_lower:
+                current_id = t.get("tenantId", "")
+                break
+
+    if current_id:
+        logger.log("tenant", f"Current tenant ID: {current_id[:8]}...")
+
+    # Look up the current tenant's display name from the list
+    current_tenant_entry = next((t for t in tenants if t.get("tenantId") == current_id), None)
+    current_display = (
+        current_tenant_entry.get("tenantPrimaryDomainName")
+        or current_tenant_entry.get("tenantName", current_id or current_name)
+        if current_tenant_entry
+        else current_name or current_id
+    )
+    logger.log("tenant", f"Current tenant: {current_display}")
+
+    # Step 3: match the requested tenant
+    matched = match_tenant(config.tenant, tenants)
+
+    if matched is None:
+        # Requested tenant not found in available tenants
+        available = [_tenant_domain(t, "?") for t in tenants]
+        available_str = ", ".join(available) if available else "(none discovered)"
+        exit_error(
+            EXIT_TENANT_NOT_FOUND,
+            ERROR_TENANT_NOT_FOUND,
+            f"Tenant '{config.tenant}' not found. Available tenants: {available_str}",
+            format_json=format_json,
+        )
+
+    # Step 4: check if the matched tenant is the current tenant
+    matched_id = matched.get("tenantId", "")
+    if matched_id != current_id:
+        matched_domain = _tenant_domain(matched, config.tenant)
+        logger.log(
+            "tenant",
+            f"Tenant mismatch: on '{current_display}', need '{matched_domain}'. "
+            f"Will switch automatically.",
+        )
+        raise TenantSwitchNeededError(tenant_id=matched_id, domain=matched_domain)
+
+    # Tenant matches -- return the domain for inclusion in output
+    matched_domain = _tenant_domain(matched, config.tenant)
+    logger.log("tenant", f"Tenant verified: {matched_domain}")
+    return TenantVerification(tenant_id=matched_id, domain=matched_domain)
+
+
+# ---------------------------------------------------------------------------
+# format_tenants_text (pure function)
+# ---------------------------------------------------------------------------
+
+
+def format_tenants_text(
+    tenants: list[dict],
+    current_tenant: dict | None,
+) -> str:
+    """Format a list of tenants as a human-readable text table.
+
+    Columns: NAME, DOMAIN, TENANT ID.  The current tenant (matched by
+    ``tenantId``) is marked with ``*``.  Column widths are computed
+    dynamically from the data.
+
+    Args:
+        tenants: List of tenant dicts (each with ``tenantId``,
+            ``tenantName``, ``tenantPrimaryDomainName``).
+        current_tenant: Dict with at least ``tenantId`` for the
+            currently active tenant, or ``None`` if unknown.
+
+    Returns:
+        A multi-line string containing the formatted table.
+    """
+    if not tenants:
+        return "No tenants found."
+
+    current_id = (current_tenant or {}).get("tenantId", "")
+
+    # Build row data: (is_current, name, domain, tenant_id)
+    rows: list[tuple[bool, str, str, str]] = []
+    for t in tenants:
+        tid = t.get("tenantId", "")
+        name = t.get("tenantName", "")
+        domain = t.get("tenantPrimaryDomainName", "")
+        is_current = bool(current_id and tid == current_id)
+        rows.append((is_current, name, domain, tid))
+
+    # Compute column widths (minimum: header lengths)
+    hdr_name, hdr_domain, hdr_id = "NAME", "DOMAIN", "TENANT ID"
+    w_name = max(len(hdr_name), *(len(r[1]) for r in rows))
+    w_domain = max(len(hdr_domain), *(len(r[2]) for r in rows))
+    w_id = max(len(hdr_id), *(len(r[3]) for r in rows))
+
+    lines: list[str] = []
+    lines.append("Available tenants (* = current):")
+    lines.append("")
+
+    # Header
+    marker_col = "    "  # 4 chars: "  * " or "    "
+    lines.append(f"{marker_col}{hdr_name:<{w_name}}  {hdr_domain:<{w_domain}}  {hdr_id:<{w_id}}")
+
+    # Data rows
+    for is_current, name, domain, tid in rows:
+        marker = "  * " if is_current else "    "
+        lines.append(f"{marker}{name:<{w_name}}  {domain:<{w_domain}}  {tid:<{w_id}}")
+
+    lines.append("")
+    lines.append("Use --tenant NAME_OR_DOMAIN to select a tenant for download.")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# format_tenants_json (pure function)
+# ---------------------------------------------------------------------------
+
+
+def format_tenants_json(
+    tenants: list[dict],
+    current_tenant: dict | None,
+) -> str:
+    """Format a list of tenants as a JSON array.
+
+    Each entry has ``tenantId``, ``tenantName``, ``domain``
+    (from ``tenantPrimaryDomainName``), and ``current`` (boolean).
+
+    Args:
+        tenants: List of tenant dicts.
+        current_tenant: Dict with ``tenantId`` for the current tenant,
+            or ``None``.
+
+    Returns:
+        A pretty-printed JSON string.
+    """
+    current_id = (current_tenant or {}).get("tenantId", "")
+
+    entries = []
+    for t in tenants:
+        tid = t.get("tenantId", "")
+        entries.append(
+            {
+                "tenantId": tid,
+                "tenantName": t.get("tenantName", ""),
+                "domain": t.get("tenantPrimaryDomainName", ""),
+                "current": bool(current_id and tid == current_id),
+            }
+        )
+
+    return json.dumps(entries, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# run_list_tenants (async orchestrator for --list-tenants)
+# ---------------------------------------------------------------------------
+
+
+async def run_list_tenants(
+    port: int,
+    *,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    format_json: bool,
+    output_path: str | None = None,
+    force_restart: bool = False,
+) -> None:
+    """List all available tenants and print to stdout or file.
+
+    Connects to Teams via CDP, discovers page targets, detects the
+    current tenant, lists all available tenants, formats the output,
+    and writes it to ``output_path`` (or stdout if ``None``).
+
+    Args:
+        port: CDP debugging port number.
+        logger: Logger instance.
+        shutdown: Shutdown coordinator for interruptible sleeps.
+        format_json: If ``True``, output JSON; otherwise text table.
+        output_path: File path to write to, or ``None`` for stdout.
+    """
+    from teams_transcripts.adapters.cdp.browser import CdpBrowserAdapter
+    from teams_transcripts.adapters.cdp.helpers import find_teams_targets, verify_cdp
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+    from teams_transcripts.infrastructure.errors import EXIT_CDP_UNAVAILABLE, exit_error
+
+    # Step 1: Ensure Teams is running with CDP
+    ensure_teams_running(
+        port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=format_json,
+        force=force_restart,
+    )
+
+    # Step 2: Verify CDP
+    verify_cdp(port, logger=logger, shutdown=shutdown, format_json=format_json)
+
+    # Step 3: Discover Teams targets
+    targets = find_teams_targets(port, logger=logger, format_json=format_json)
+    if not targets:
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "NO_TARGETS",
+            "No Teams page targets found via CDP.",
+            step="list-tenants",
+            format_json=format_json,
+        )
+    logger.log("list-tenants", f"Found {len(targets)} Teams page target(s)")
+
+    # Pick the best target for tenant detection
+    target_id = pick_detection_target(targets)
+
+    # Connect and detect/list tenants
+    browser = CdpBrowserAdapter(port=port)
+    await browser.connect(target_id)
+    try:
+        current = await detect_current_tenant(browser)
+        tenants = await list_available_tenants(browser)
+    finally:
+        await browser.disconnect()
+
+    # Format output
+    if format_json:
+        output = format_tenants_json(tenants, current)
+    else:
+        output = format_tenants_text(tenants, current)
+
+    # Write to file or stdout
+    if output_path:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(output)
+            f.write("\n")
+        logger.log("list-tenants", f"Tenant list written to {output_path}")
+    else:
+        print(output)
+
+    sys.exit(0)