power-admin 0.1.0__tar.gz

power_admin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest -q
+      - run: uv build

power_admin-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+# Publish to PyPI when a GitHub release is published (tag like v0.1.0).
+# Uses PyPI trusted publishing, so no API token is stored in GitHub.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/power-admin
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check tag matches package version
+        run: |
+          version=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          if [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+      - run: uv sync --locked
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uv publish

power_admin-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+power-admin-output/
+.pytest_cache/

power_admin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

power_admin-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: power-admin
+Version: 0.1.0
+Summary: Pull Power Platform admin data (inventory, capacity, Copilot credits, users) to a local folder or S3.
+Project-URL: Homepage, https://github.com/emptymalei/power-admin
+Project-URL: Issues, https://github.com/emptymalei/power-admin/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,copilot-studio,governance,inventory,power-apps,power-automate,power-platform
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: cloudpathlib[s3]>=0.18
+Requires-Dist: msal>=1.28
+Requires-Dist: requests>=2.31
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# power-admin
+
+A small CLI that signs in to your Microsoft tenant and pulls Power Platform admin data into dated snapshots. You can save to a local folder or to S3.
+
+> Community tool. Not affiliated with or endorsed by Microsoft.
+
+| Dataset | What's in it | Source |
+| --- | --- | --- |
+| `environments` | Environments, their type and region, Dataverse details | Power Platform API `environmentmanagement` |
+| `inventory`, `agents`, `apps`, `flows` | Every canvas, model-driven and code app, every cloud and agent flow, and every Copilot Studio agent, joined to its environment | Power Platform inventory API (`PowerPlatformResources`) |
+| `capacity`, `capacity_raw`, `currency` | Tenant storage and API capacity, plus purchased, allocated and consumed amounts per currency (Copilot credits, AI Builder and others) | Power Platform API `licensing/tenantCapacity` |
+| `agent_credits` | Copilot credit consumption per agent and environment for a date range, with agent names attached | Power Platform API `licensing/entitlements/{id}/resources` |
+| `users`, `licenses`, `user_licenses` | Entra users, the tenant's license SKUs, and which user has which SKU | Microsoft Graph |
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/). In PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # if you don't have uv
+uvx power-admin --help          # run without installing (once published to PyPI)
+uv tool install power-admin     # or put `power-admin` on your PATH
+# from a local checkout: uv tool install .
+```
+
+## Setup
+
+You don't need your own Entra app. For `interactive` and `device-code` sign-in, power-admin uses the public client ID of Microsoft's Azure PowerShell app (`1950a258-227b-4e31-a9cf-717495945fc2`), which is the same one `Connect-AzAccount` uses. That app is already pre-authorized for the Power Platform API and Microsoft Graph, and it doesn't need an Azure subscription. Data access still comes from your own admin roles.
+
+```powershell
+power-admin configure --tenant-id contoso.onmicrosoft.com --output C:\power-admin
+```
+
+Your account needs the Power Platform Administrator role (or Global Administrator / Global Reader) so it can see the whole tenant. Graph reads need a role that can read users, such as Global Reader or User Administrator.
+
+### Optional: use your own app registration
+
+Use your own app if your tenant blocks the Azure PowerShell client through Conditional Access, if you want consent scoped to exactly these permissions, or if you need app-only auth.
+
+1. Go to **Entra admin center > App registrations > New registration**. Choose **single tenant**.
+2. Under **Authentication**, add the platform **Mobile and desktop applications** with the redirect URI `http://localhost`. If you'll use device-code sign-in, also set **Allow public client flows** to **Yes**.
+3. Under **API permissions**, add the following **delegated** permissions, then click **Grant admin consent**:
+   - **Power Platform API** (`8578e004-a5c6-46e7-913e-12f58912df43`): `ResourceQuery.Resources.Read`, `EnvironmentManagement.Environments.Read`, `Licensing.Allocations.Read`.
+     If the API doesn't show up in the list, run `New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43` once, using Microsoft Graph PowerShell.
+   - **Microsoft Graph**: `User.Read.All`, `Organization.Read.All`.
+4. Pass `--client-id <app-id>` to `power-admin configure`.
+
+### Or reuse an existing PowerShell sign-in
+
+If you're already signed in with the Az module, you can hand those tokens to power-admin:
+
+```powershell
+Connect-AzAccount -Tenant contoso.onmicrosoft.com   # warns that there are no subscriptions, which is fine
+$pp = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com" -AsSecureString
+$gr = Get-AzAccessToken -ResourceTypeName MSGraph -AsSecureString
+$env:POWER_ADMIN_PP_TOKEN    = $pp.Token | ConvertFrom-SecureString -AsPlainText
+$env:POWER_ADMIN_GRAPH_TOKEN = $gr.Token | ConvertFrom-SecureString -AsPlainText
+power-admin pull --auth token
+```
+
+Tokens last about an hour.
+
+## Use
+
+```powershell
+power-admin login                       # opens a browser; the sign-in is cached in ~/.power-admin
+power-admin pull                        # everything, credits from the 1st of last month to today
+power-admin pull -o s3://my-bucket/power-platform --aws-profile admin
+power-admin pull --only credits --from 2026-10-01 --to 2026-10-31
+power-admin pull --skip users -f csv    # CSV only
+power-admin datasets                    # list what can be pulled
+power-admin status                      # show settings and who's signed in
+power-admin logout
+```
+
+Output layout. It's the same for a local folder and for S3, and it's partitioned so that Athena and Glue can read it directly:
+
+```
+<output>/agents/snapshot_date=2026-10-30/agents.jsonl
+<output>/agents/snapshot_date=2026-10-30/agents.csv
+<output>/agent_credits/snapshot_date=2026-10-30/agent_credits.csv
+<output>/_runs/20261030T212400Z.json      # row counts and any errors for the run
+```
+
+Every run adds a new `snapshot_date`, so you build up history. If any dataset fails, the run still saves the rest, records the error in the manifest, and exits with code 1.
+
+S3 uploads use the normal AWS credential chain, or the profile you pass with `--aws-profile`. Run `aws sso login --profile admin` first if you use SSO.
+
+## Auth modes
+
+Pick a mode with `--auth` / `-a`, or set it in `power-admin configure` or with `POWER_ADMIN_AUTH_MODE`.
+
+| Mode | When to use | Needs |
+| --- | --- | --- |
+| `interactive` (default) | You, at your desk. Opens a browser. | `--tenant-id` (`--client-id` is optional) |
+| `device-code` | Remote or SSH shells, or when a browser can't open. You enter a code at microsoft.com/devicelogin. | Same (with your own app, also turn on **Allow public client flows**) |
+| `client-secret` | Unattended runs | `--tenant-id`, `--client-id`, `POWER_ADMIN_CLIENT_SECRET` |
+| `certificate` | Unattended runs without secrets | `--certificate-path` (PEM private key) and `--certificate-thumbprint` |
+| `token` | You already signed in with `Connect-AzAccount` or another tool | `POWER_ADMIN_PP_TOKEN` and `POWER_ADMIN_GRAPH_TOKEN` env vars |
+
+How the app-only modes (`client-secret`, `certificate`) differ:
+- **The inventory API rejects app-only tokens.** Microsoft only supports signed-in users there, so in these modes `inventory` is skipped and listed in the manifest.
+- **The service principal needs extra access.** It must be given a Power Platform RBAC role (see Microsoft's guide *Assign RBAC roles to service principals*), and for `users` it needs the Graph *application* permissions `User.Read.All` and `Organization.Read.All`.
+
+For monthly manual runs, `interactive` is the simplest option.
+
+## Caveats
+
+- **The per-agent credit endpoints may change or fail.** They are marked *deprecated* in the Power Platform API reference but still documented. The entitlement ID `MCSMessages` (Copilot credits) is our best reading of the docs and hasn't been tested against a live tenant yet; if you get a 400 or 404, try `--credit-entitlement` with another value. Whatever happens, the admin center's **Licensing > Copilot Studio > Download report** remains the authoritative source.
+- **Several licensing APIs are still in preview**, so their field names may change. JSONL keeps the full raw response; CSV flattens nested fields into `a.b.c` columns.
+- **Usage metrics are missing.** Per-app users, per-flow runs and per-agent sessions from the admin center's Usage page don't have a public API yet.
+
+## Querying in Athena (optional)
+
+```sql
+CREATE EXTERNAL TABLE agent_credits (
+  resourceId string, resourceName string, environmentId string, environmentName string,
+  consumed double, unit string, lastRefreshedDate string, periodFrom string, periodTo string
+)
+PARTITIONED BY (snapshot_date string)
+ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
+LOCATION 's3://my-bucket/power-platform/agent_credits/';
+MSCK REPAIR TABLE agent_credits;
+```
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Releasing
+
+CI runs the tests on every push and pull request. Publishing a GitHub release whose tag is `v<version>` (for example `v0.1.0`, matching `version` in `pyproject.toml`) builds the package and uploads it to PyPI.
+
+The release uses PyPI trusted publishing, so no token is stored in GitHub. One-time setup:
+1. Add a pending publisher on PyPI under **Your account > Publishing**, with project `power-admin`, owner `emptymalei`, repository `power-admin`, workflow `release.yml` and environment `pypi`.
+2. In the GitHub repo, open **Settings > Environments** and create an environment called `pypi`.

power_admin-0.1.0/README.md

@@ -0,0 +1,139 @@
+# power-admin
+
+A small CLI that signs in to your Microsoft tenant and pulls Power Platform admin data into dated snapshots. You can save to a local folder or to S3.
+
+> Community tool. Not affiliated with or endorsed by Microsoft.
+
+| Dataset | What's in it | Source |
+| --- | --- | --- |
+| `environments` | Environments, their type and region, Dataverse details | Power Platform API `environmentmanagement` |
+| `inventory`, `agents`, `apps`, `flows` | Every canvas, model-driven and code app, every cloud and agent flow, and every Copilot Studio agent, joined to its environment | Power Platform inventory API (`PowerPlatformResources`) |
+| `capacity`, `capacity_raw`, `currency` | Tenant storage and API capacity, plus purchased, allocated and consumed amounts per currency (Copilot credits, AI Builder and others) | Power Platform API `licensing/tenantCapacity` |
+| `agent_credits` | Copilot credit consumption per agent and environment for a date range, with agent names attached | Power Platform API `licensing/entitlements/{id}/resources` |
+| `users`, `licenses`, `user_licenses` | Entra users, the tenant's license SKUs, and which user has which SKU | Microsoft Graph |
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/). In PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # if you don't have uv
+uvx power-admin --help          # run without installing (once published to PyPI)
+uv tool install power-admin     # or put `power-admin` on your PATH
+# from a local checkout: uv tool install .
+```
+
+## Setup
+
+You don't need your own Entra app. For `interactive` and `device-code` sign-in, power-admin uses the public client ID of Microsoft's Azure PowerShell app (`1950a258-227b-4e31-a9cf-717495945fc2`), which is the same one `Connect-AzAccount` uses. That app is already pre-authorized for the Power Platform API and Microsoft Graph, and it doesn't need an Azure subscription. Data access still comes from your own admin roles.
+
+```powershell
+power-admin configure --tenant-id contoso.onmicrosoft.com --output C:\power-admin
+```
+
+Your account needs the Power Platform Administrator role (or Global Administrator / Global Reader) so it can see the whole tenant. Graph reads need a role that can read users, such as Global Reader or User Administrator.
+
+### Optional: use your own app registration
+
+Use your own app if your tenant blocks the Azure PowerShell client through Conditional Access, if you want consent scoped to exactly these permissions, or if you need app-only auth.
+
+1. Go to **Entra admin center > App registrations > New registration**. Choose **single tenant**.
+2. Under **Authentication**, add the platform **Mobile and desktop applications** with the redirect URI `http://localhost`. If you'll use device-code sign-in, also set **Allow public client flows** to **Yes**.
+3. Under **API permissions**, add the following **delegated** permissions, then click **Grant admin consent**:
+   - **Power Platform API** (`8578e004-a5c6-46e7-913e-12f58912df43`): `ResourceQuery.Resources.Read`, `EnvironmentManagement.Environments.Read`, `Licensing.Allocations.Read`.
+     If the API doesn't show up in the list, run `New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43` once, using Microsoft Graph PowerShell.
+   - **Microsoft Graph**: `User.Read.All`, `Organization.Read.All`.
+4. Pass `--client-id <app-id>` to `power-admin configure`.
+
+### Or reuse an existing PowerShell sign-in
+
+If you're already signed in with the Az module, you can hand those tokens to power-admin:
+
+```powershell
+Connect-AzAccount -Tenant contoso.onmicrosoft.com   # warns that there are no subscriptions, which is fine
+$pp = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com" -AsSecureString
+$gr = Get-AzAccessToken -ResourceTypeName MSGraph -AsSecureString
+$env:POWER_ADMIN_PP_TOKEN    = $pp.Token | ConvertFrom-SecureString -AsPlainText
+$env:POWER_ADMIN_GRAPH_TOKEN = $gr.Token | ConvertFrom-SecureString -AsPlainText
+power-admin pull --auth token
+```
+
+Tokens last about an hour.
+
+## Use
+
+```powershell
+power-admin login                       # opens a browser; the sign-in is cached in ~/.power-admin
+power-admin pull                        # everything, credits from the 1st of last month to today
+power-admin pull -o s3://my-bucket/power-platform --aws-profile admin
+power-admin pull --only credits --from 2026-10-01 --to 2026-10-31
+power-admin pull --skip users -f csv    # CSV only
+power-admin datasets                    # list what can be pulled
+power-admin status                      # show settings and who's signed in
+power-admin logout
+```
+
+Output layout. It's the same for a local folder and for S3, and it's partitioned so that Athena and Glue can read it directly:
+
+```
+<output>/agents/snapshot_date=2026-10-30/agents.jsonl
+<output>/agents/snapshot_date=2026-10-30/agents.csv
+<output>/agent_credits/snapshot_date=2026-10-30/agent_credits.csv
+<output>/_runs/20261030T212400Z.json      # row counts and any errors for the run
+```
+
+Every run adds a new `snapshot_date`, so you build up history. If any dataset fails, the run still saves the rest, records the error in the manifest, and exits with code 1.
+
+S3 uploads use the normal AWS credential chain, or the profile you pass with `--aws-profile`. Run `aws sso login --profile admin` first if you use SSO.
+
+## Auth modes
+
+Pick a mode with `--auth` / `-a`, or set it in `power-admin configure` or with `POWER_ADMIN_AUTH_MODE`.
+
+| Mode | When to use | Needs |
+| --- | --- | --- |
+| `interactive` (default) | You, at your desk. Opens a browser. | `--tenant-id` (`--client-id` is optional) |
+| `device-code` | Remote or SSH shells, or when a browser can't open. You enter a code at microsoft.com/devicelogin. | Same (with your own app, also turn on **Allow public client flows**) |
+| `client-secret` | Unattended runs | `--tenant-id`, `--client-id`, `POWER_ADMIN_CLIENT_SECRET` |
+| `certificate` | Unattended runs without secrets | `--certificate-path` (PEM private key) and `--certificate-thumbprint` |
+| `token` | You already signed in with `Connect-AzAccount` or another tool | `POWER_ADMIN_PP_TOKEN` and `POWER_ADMIN_GRAPH_TOKEN` env vars |
+
+How the app-only modes (`client-secret`, `certificate`) differ:
+- **The inventory API rejects app-only tokens.** Microsoft only supports signed-in users there, so in these modes `inventory` is skipped and listed in the manifest.
+- **The service principal needs extra access.** It must be given a Power Platform RBAC role (see Microsoft's guide *Assign RBAC roles to service principals*), and for `users` it needs the Graph *application* permissions `User.Read.All` and `Organization.Read.All`.
+
+For monthly manual runs, `interactive` is the simplest option.
+
+## Caveats
+
+- **The per-agent credit endpoints may change or fail.** They are marked *deprecated* in the Power Platform API reference but still documented. The entitlement ID `MCSMessages` (Copilot credits) is our best reading of the docs and hasn't been tested against a live tenant yet; if you get a 400 or 404, try `--credit-entitlement` with another value. Whatever happens, the admin center's **Licensing > Copilot Studio > Download report** remains the authoritative source.
+- **Several licensing APIs are still in preview**, so their field names may change. JSONL keeps the full raw response; CSV flattens nested fields into `a.b.c` columns.
+- **Usage metrics are missing.** Per-app users, per-flow runs and per-agent sessions from the admin center's Usage page don't have a public API yet.
+
+## Querying in Athena (optional)
+
+```sql
+CREATE EXTERNAL TABLE agent_credits (
+  resourceId string, resourceName string, environmentId string, environmentName string,
+  consumed double, unit string, lastRefreshedDate string, periodFrom string, periodTo string
+)
+PARTITIONED BY (snapshot_date string)
+ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
+LOCATION 's3://my-bucket/power-platform/agent_credits/';
+MSCK REPAIR TABLE agent_credits;
+```
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Releasing
+
+CI runs the tests on every push and pull request. Publishing a GitHub release whose tag is `v<version>` (for example `v0.1.0`, matching `version` in `pyproject.toml`) builds the package and uploads it to PyPI.
+
+The release uses PyPI trusted publishing, so no token is stored in GitHub. One-time setup:
+1. Add a pending publisher on PyPI under **Your account > Publishing**, with project `power-admin`, owner `emptymalei`, repository `power-admin`, workflow `release.yml` and environment `pypi`.
+2. In the GitHub repo, open **Settings > Environments** and create an environment called `pypi`.

power_admin-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "power-admin"
+version = "0.1.0"
+description = "Pull Power Platform admin data (inventory, capacity, Copilot credits, users) to a local folder or S3."
+readme = "README.md"
+license = "MIT"
+keywords = ["power-platform", "copilot-studio", "power-apps", "power-automate", "admin", "inventory", "governance"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+    "msal>=1.28",
+    "requests>=2.31",
+    "cloudpathlib[s3]>=0.18",
+]
+
+[project.urls]
+Homepage = "https://github.com/emptymalei/power-admin"
+Issues = "https://github.com/emptymalei/power-admin/issues"
+
+[project.scripts]
+power-admin = "power_admin.cli:app"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/power_admin"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

power_admin-0.1.0/src/power_admin/__init__.py

@@ -0,0 +1,3 @@
+"""Power Platform admin data puller."""
+
+__version__ = "0.1.0"

power_admin-0.1.0/src/power_admin/auth.py

@@ -0,0 +1,161 @@
+"""Token acquisition for the Power Platform API and Microsoft Graph.
+
+Supported modes:
+  interactive    browser sign-in as you (delegated). Default.
+  device-code    sign in on any device with a code (delegated). Good for SSH or locked-down shells.
+  client-secret  app-only service principal with a client secret.
+  certificate    app-only service principal with a certificate (PEM private key + thumbprint).
+  token          bring your own access tokens via POWER_ADMIN_PP_TOKEN / POWER_ADMIN_GRAPH_TOKEN.
+
+Delegated modes cache tokens in ~/.power-admin, so you sign in once and later runs are silent
+until the refresh token expires. Note the Power Platform inventory API only accepts
+delegated (user) tokens; app-only modes get 403 there.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Callable
+
+import msal
+
+from .config import GRAPH_SCOPE, PP_SCOPE, TOKEN_CACHE_FILE, Settings
+
+DELEGATED_MODES = {"interactive", "device-code"}
+
+# Microsoft's public client ID for Azure PowerShell (the one Connect-AzAccount uses). It is
+# pre-authorized for the Power Platform API and Graph, so delegated sign-in works without
+# registering your own Entra app. Override with --client-id if your tenant blocks it.
+DEFAULT_PUBLIC_CLIENT_ID = "1950a258-227b-4e31-a9cf-717495945fc2"
+APP_ONLY_MODES = {"client-secret", "certificate"}
+
+_TOKEN_ENV = {PP_SCOPE: "POWER_ADMIN_PP_TOKEN", GRAPH_SCOPE: "POWER_ADMIN_GRAPH_TOKEN"}
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+def _load_cache() -> msal.SerializableTokenCache:
+    cache = msal.SerializableTokenCache()
+    if TOKEN_CACHE_FILE.exists():
+        cache.deserialize(TOKEN_CACHE_FILE.read_text(encoding="utf-8"))
+    return cache
+
+
+def _save_cache(cache: msal.SerializableTokenCache) -> None:
+    if cache.has_state_changed:
+        TOKEN_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        TOKEN_CACHE_FILE.write_text(cache.serialize(), encoding="utf-8")
+        try:
+            os.chmod(TOKEN_CACHE_FILE, 0o600)
+        except OSError:
+            pass
+
+
+class TokenProvider:
+    """Returns bearer tokens per scope, signing in on first use."""
+
+    def __init__(self, settings: Settings, echo: Callable[[str], None] = print):
+        self.settings = settings
+        self.echo = echo
+        self._cache = _load_cache()
+        self._app: msal.ClientApplication | None = None
+        self._memo: dict[str, str] = {}
+
+    @property
+    def mode(self) -> str:
+        return self.settings.auth_mode
+
+    @property
+    def is_delegated(self) -> bool:
+        return self.mode in DELEGATED_MODES or self.mode == "token"
+
+    def _require(self, *names: str) -> None:
+        missing = [n for n in names if not getattr(self.settings, n)]
+        if missing:
+            flags = ", ".join("--" + n.replace("_", "-") for n in missing)
+            raise AuthError(f"Auth mode {self.mode!r} needs {flags} (or the matching POWER_ADMIN_* env vars)")
+
+    def _client(self) -> msal.ClientApplication:
+        if self._app is not None:
+            return self._app
+        s = self.settings
+        if self.mode in DELEGATED_MODES:
+            self._app = msal.PublicClientApplication(
+                s.client_id or DEFAULT_PUBLIC_CLIENT_ID, authority=s.authority, token_cache=self._cache
+            )
+        elif self.mode == "client-secret":
+            self._require("tenant_id", "client_id", "client_secret")
+            self._app = msal.ConfidentialClientApplication(
+                s.client_id, authority=s.authority, client_credential=s.client_secret, token_cache=self._cache
+            )
+        elif self.mode == "certificate":
+            self._require("tenant_id", "client_id", "certificate_path", "certificate_thumbprint")
+            key = Path(s.certificate_path).read_text(encoding="utf-8")
+            self._app = msal.ConfidentialClientApplication(
+                s.client_id,
+                authority=s.authority,
+                client_credential={"private_key": key, "thumbprint": s.certificate_thumbprint},
+                token_cache=self._cache,
+            )
+        else:
+            raise AuthError(f"Auth mode {self.mode!r} does not use MSAL")
+        return self._app
+
+    def get_token(self, scope: str) -> str:
+        if scope in self._memo:
+            return self._memo[scope]
+        token = self._acquire(scope)
+        self._memo[scope] = token
+        return token
+
+    def _acquire(self, scope: str) -> str:
+        if self.mode == "token":
+            env = _TOKEN_ENV.get(scope)
+            value = os.environ.get(env or "")
+            if not value:
+                raise AuthError(f"Auth mode 'token' needs the {env} environment variable for {scope}")
+            return value
+
+        app = self._client()
+        scopes = [scope]
+        result = None
+        if self.mode in APP_ONLY_MODES:
+            result = app.acquire_token_for_client(scopes=scopes)
+        else:
+            accounts = app.get_accounts()
+            if accounts:
+                result = app.acquire_token_silent(scopes, account=accounts[0])
+            if not result:
+                result = self._sign_in(app, scopes)
+        _save_cache(self._cache)
+
+        if not result or "access_token" not in result:
+            detail = (result or {}).get("error_description") or (result or {}).get("error") or "no token returned"
+            raise AuthError(f"Could not get a token for {scope}: {detail}")
+        return result["access_token"]
+
+    def _sign_in(self, app: msal.PublicClientApplication, scopes: list[str]) -> dict:
+        if self.mode == "device-code":
+            flow = app.initiate_device_flow(scopes=scopes)
+            if "user_code" not in flow:
+                raise AuthError(f"Device code flow failed: {flow.get('error_description', flow)}")
+            self.echo(flow["message"])
+            return app.acquire_token_by_device_flow(flow)
+        self.echo("Opening a browser window to sign in...")
+        return app.acquire_token_interactive(scopes=scopes, prompt="select_account")
+
+    def signed_in_user(self) -> str | None:
+        if self.mode not in DELEGATED_MODES:
+            return None
+        accounts = self._client().get_accounts()
+        return accounts[0].get("username") if accounts else None
+
+
+def logout() -> bool:
+    if TOKEN_CACHE_FILE.exists():
+        TOKEN_CACHE_FILE.unlink()
+        return True
+    return False