granola-cli 0.1.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync (with dev group)
+        run: uv sync --group dev
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github .
+
+  test:
+    name: pytest (${{ matrix.os }} / py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Sync (with dev group)
+        run: uv sync --group dev
+      - name: Run tests
+        run: uv run pytest

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

@@ -0,0 +1,55 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:        # manual run -> TestPyPI (for testing the publish flow)
+
+jobs:
+  build:
+    name: build artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check metadata renders
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    name: publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write        # OIDC -> trusted publishing, no stored token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

granola_cli-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+
+# Secrets — never commit decrypted creds or tokens
+*.enc
+*.dek
+*.bak-*
+*credentials*.json
+*token*.json
+.env*
+
+# Local data / scratch
+*.db
+notes/
+tmp/

granola_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Granola CLI contributors
+
+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.

granola_cli-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: granola-cli
+Version: 0.1.0
+Summary: One CLI for Granola: decrypt on-disk creds and drive the documented internal API (read/share/edit notes).
+Project-URL: Homepage, https://github.com/xuelongmu/granola-cli
+Project-URL: Repository, https://github.com/xuelongmu/granola-cli
+Project-URL: Issues, https://github.com/xuelongmu/granola-cli/issues
+Author: Granola CLI contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,granola,meeting-notes,transcripts
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# granola
+
+One CLI for [Granola](https://granola.ai) on **Windows & macOS** — using Granola's own
+on-disk session, no API key, no password prompt. It covers two things:
+
+1. **Credentials** — decrypt the on-disk chain (Windows DPAPI / macOS Keychain → DEK →
+   cred file), auto-**refresh** the token (single-use rotation, with safe write-back),
+   print it, or export a portable **session file** for headless/Linux use.
+2. **The documented internal API** for a note — read, share, edit — plus a generic
+   `call` for any of the ~392 internal endpoints.
+
+> Unofficial. Uses the internal `api.granola.ai` surface the desktop app uses; it can
+> change without notice. Credential decrypt works on **Windows** (DPAPI) and **macOS**
+> (Keychain); the API layer is portable once you have a token.
+
+## Install
+
+```powershell
+uv tool install .          # or: pipx install .
+granola auth status
+```
+
+Requires Python ≥ 3.10. Dependencies: `httpx`, `cryptography`.
+
+## Usage
+
+```text
+# auth / engine
+granola auth status                  # token status (no secrets; --include-secrets to show)
+granola auth token                   # print a valid access token
+granola auth refresh                 # force-refresh the selected source
+granola auth export session.json     # write a portable, refreshable session file (0600)
+granola routes [filter]              # endpoint name -> URL map
+granola call <endpoint> --body '{"limit":5}'   # any endpoint, raw
+
+# read
+granola notes --limit 20             # recent notes
+granola get <id>                     # full ~50-field record (--json for all)
+granola meta <id>                    # creator / attendees / conferencing
+granola transcript <id>              # transcript as markdown
+granola panels <id>                  # AI summary panels
+
+# share / access
+granola who <id>                                     # who has access (+ user_ids)
+granola share <id> --email teammate@example.com --name "Teammate"  # add collaborator
+granola unshare <id> --email teammate@example.com                  # revoke (no email sent)
+granola role <id> --user <user_id> --role viewer     # change role
+granola folder-who "Team Notes"                       # who has folder-level access
+granola share-folder "Team Notes" --email teammate@example.com       # folder ACL (existing users; inherited access)
+granola share-folder "Team Notes" --email teammate@example.com --per-note   # invite + direct access on each note
+granola unshare-folder "Team Notes" --email teammate@example.com     # revoke folder-level access
+
+# edit
+granola update <id> --title "New title"
+granola delete <id> --yes            # PERMANENT hard delete
+```
+
+Roles: `owner` · `collaborator` · `viewer`.
+
+See [`docs/api-gotchas.md`](docs/api-gotchas.md) for endpoint quirks baked into the
+typed verbs.
+
+## Headless / portable sessions
+
+Credential decrypt needs the Keychain (macOS) or DPAPI (Windows), so it only runs on
+the machine you signed in on. To drive the API from a headless Linux box or CI, export
+a **session file** once and carry it over:
+
+```bash
+# On your macOS/Windows machine (where Granola is signed in):
+granola auth export ~/session.json     # minimal, refreshable, written 0600
+
+# Sign OUT of the Granola desktop app, so only this session holds the refresh token.
+# (Desktop + session sharing one single-use refresh token will fight and log each
+#  other out on rotation.)
+
+# On the headless box:
+export GRANOLA_SESSION=~/session.json
+granola notes --limit 20               # refreshes + writes back to the file in place
+```
+
+Every command takes global auth options (before the command) that pick the token source:
+
+```text
+--email EMAIL          select an account from local desktop credentials
+--session PATH         use a refreshable session file
+--access-token TOKEN   use this bearer token directly (no refresh)
+--no-refresh           never auto-refresh
+```
+
+Environment equivalents: `GRANOLA_SESSION`, `GRANOLA_ACCESS_TOKEN`.
+
+**Precedence:** a refreshable session (`--session` / `GRANOLA_SESSION`) beats a static
+token (`--access-token` / `GRANOLA_ACCESS_TOKEN`); a flag beats its env var; the desktop
+store is the fallback. If both a static token and a session are set, the session wins and
+the CLI warns — a static token can't refresh and would silently go stale.
+
+Use `--access-token` (or `granola auth export --no-refresh-token`) for short-lived CI where
+you don't want a long-lived rotating secret on the box.
+
+If a session's refresh token ever dies (the desktop rotated it, or it was revoked), you
+can't re-bootstrap headlessly — re-run `granola auth export` on your macOS/Windows machine
+and copy the file over.
+
+## Platforms
+
+| | Windows | macOS |
+|---|---|---|
+| Data dir | `%APPDATA%\Granola` | `~/Library/Application Support/Granola` |
+| Key source | `Local State` → **DPAPI** (CurrentUser) | login **Keychain** item `Granola Safe Storage` / `Granola Key` |
+| `storage.dek` unwrap | AES-256-GCM (Chromium key) | AES-128-CBC (PBKDF2 `saltysalt`/1003 — Electron safeStorage) |
+| Cred file | `stored-accounts.json.enc` (`accounts[].tokens`) | `supabase.json.enc` (`workos_tokens`) |
+| Final decrypt | AES-256-GCM(DEK) | AES-256-GCM(DEK) |
+
+The decrypt must run as the logged-in user (DPAPI / Keychain are user-scoped). On macOS
+the **first** run may show a Keychain access prompt for the `Granola Safe Storage` item —
+allow it. The macOS crypto is verified against
+[harperreed/muesli](https://github.com/harperreed/muesli)'s known-good vectors
+(`tests/test_macos_crypto.py`).
+
+## Layout
+
+```
+granola/
+  config, crypto, _http, store        # engine: decrypt the on-disk cred chain
+  auth.py       token primitives: refresh exchange, expiry, status (persistence-free)
+  sources.py    token sources (desktop / session-file / static) + precedence
+  routes, client                      # endpoint resolution + API client
+  notes.py      read ops (list/get/meta/transcript/panels)
+  sharing.py    collaborators (who/share/unshare/role/share-folder)
+  editing.py    update-document / hard-delete
+  cli.py        the `granola` command
+```
+
+## License
+
+MIT.

granola_cli-0.1.0/README.md

@@ -0,0 +1,137 @@
+# granola
+
+One CLI for [Granola](https://granola.ai) on **Windows & macOS** — using Granola's own
+on-disk session, no API key, no password prompt. It covers two things:
+
+1. **Credentials** — decrypt the on-disk chain (Windows DPAPI / macOS Keychain → DEK →
+   cred file), auto-**refresh** the token (single-use rotation, with safe write-back),
+   print it, or export a portable **session file** for headless/Linux use.
+2. **The documented internal API** for a note — read, share, edit — plus a generic
+   `call` for any of the ~392 internal endpoints.
+
+> Unofficial. Uses the internal `api.granola.ai` surface the desktop app uses; it can
+> change without notice. Credential decrypt works on **Windows** (DPAPI) and **macOS**
+> (Keychain); the API layer is portable once you have a token.
+
+## Install
+
+```powershell
+uv tool install .          # or: pipx install .
+granola auth status
+```
+
+Requires Python ≥ 3.10. Dependencies: `httpx`, `cryptography`.
+
+## Usage
+
+```text
+# auth / engine
+granola auth status                  # token status (no secrets; --include-secrets to show)
+granola auth token                   # print a valid access token
+granola auth refresh                 # force-refresh the selected source
+granola auth export session.json     # write a portable, refreshable session file (0600)
+granola routes [filter]              # endpoint name -> URL map
+granola call <endpoint> --body '{"limit":5}'   # any endpoint, raw
+
+# read
+granola notes --limit 20             # recent notes
+granola get <id>                     # full ~50-field record (--json for all)
+granola meta <id>                    # creator / attendees / conferencing
+granola transcript <id>              # transcript as markdown
+granola panels <id>                  # AI summary panels
+
+# share / access
+granola who <id>                                     # who has access (+ user_ids)
+granola share <id> --email teammate@example.com --name "Teammate"  # add collaborator
+granola unshare <id> --email teammate@example.com                  # revoke (no email sent)
+granola role <id> --user <user_id> --role viewer     # change role
+granola folder-who "Team Notes"                       # who has folder-level access
+granola share-folder "Team Notes" --email teammate@example.com       # folder ACL (existing users; inherited access)
+granola share-folder "Team Notes" --email teammate@example.com --per-note   # invite + direct access on each note
+granola unshare-folder "Team Notes" --email teammate@example.com     # revoke folder-level access
+
+# edit
+granola update <id> --title "New title"
+granola delete <id> --yes            # PERMANENT hard delete
+```
+
+Roles: `owner` · `collaborator` · `viewer`.
+
+See [`docs/api-gotchas.md`](docs/api-gotchas.md) for endpoint quirks baked into the
+typed verbs.
+
+## Headless / portable sessions
+
+Credential decrypt needs the Keychain (macOS) or DPAPI (Windows), so it only runs on
+the machine you signed in on. To drive the API from a headless Linux box or CI, export
+a **session file** once and carry it over:
+
+```bash
+# On your macOS/Windows machine (where Granola is signed in):
+granola auth export ~/session.json     # minimal, refreshable, written 0600
+
+# Sign OUT of the Granola desktop app, so only this session holds the refresh token.
+# (Desktop + session sharing one single-use refresh token will fight and log each
+#  other out on rotation.)
+
+# On the headless box:
+export GRANOLA_SESSION=~/session.json
+granola notes --limit 20               # refreshes + writes back to the file in place
+```
+
+Every command takes global auth options (before the command) that pick the token source:
+
+```text
+--email EMAIL          select an account from local desktop credentials
+--session PATH         use a refreshable session file
+--access-token TOKEN   use this bearer token directly (no refresh)
+--no-refresh           never auto-refresh
+```
+
+Environment equivalents: `GRANOLA_SESSION`, `GRANOLA_ACCESS_TOKEN`.
+
+**Precedence:** a refreshable session (`--session` / `GRANOLA_SESSION`) beats a static
+token (`--access-token` / `GRANOLA_ACCESS_TOKEN`); a flag beats its env var; the desktop
+store is the fallback. If both a static token and a session are set, the session wins and
+the CLI warns — a static token can't refresh and would silently go stale.
+
+Use `--access-token` (or `granola auth export --no-refresh-token`) for short-lived CI where
+you don't want a long-lived rotating secret on the box.
+
+If a session's refresh token ever dies (the desktop rotated it, or it was revoked), you
+can't re-bootstrap headlessly — re-run `granola auth export` on your macOS/Windows machine
+and copy the file over.
+
+## Platforms
+
+| | Windows | macOS |
+|---|---|---|
+| Data dir | `%APPDATA%\Granola` | `~/Library/Application Support/Granola` |
+| Key source | `Local State` → **DPAPI** (CurrentUser) | login **Keychain** item `Granola Safe Storage` / `Granola Key` |
+| `storage.dek` unwrap | AES-256-GCM (Chromium key) | AES-128-CBC (PBKDF2 `saltysalt`/1003 — Electron safeStorage) |
+| Cred file | `stored-accounts.json.enc` (`accounts[].tokens`) | `supabase.json.enc` (`workos_tokens`) |
+| Final decrypt | AES-256-GCM(DEK) | AES-256-GCM(DEK) |
+
+The decrypt must run as the logged-in user (DPAPI / Keychain are user-scoped). On macOS
+the **first** run may show a Keychain access prompt for the `Granola Safe Storage` item —
+allow it. The macOS crypto is verified against
+[harperreed/muesli](https://github.com/harperreed/muesli)'s known-good vectors
+(`tests/test_macos_crypto.py`).
+
+## Layout
+
+```
+granola/
+  config, crypto, _http, store        # engine: decrypt the on-disk cred chain
+  auth.py       token primitives: refresh exchange, expiry, status (persistence-free)
+  sources.py    token sources (desktop / session-file / static) + precedence
+  routes, client                      # endpoint resolution + API client
+  notes.py      read ops (list/get/meta/transcript/panels)
+  sharing.py    collaborators (who/share/unshare/role/share-folder)
+  editing.py    update-document / hard-delete
+  cli.py        the `granola` command
+```
+
+## License
+
+MIT.

granola_cli-0.1.0/docs/api-gotchas.md

@@ -0,0 +1,14 @@
+# API gotchas
+
+These quirks are baked into the typed verbs so callers do not have to rediscover
+them by hitting API errors.
+
+- **`share`** -> `add-users-to-document` wants `names` as an **`{email: name}` object map**,
+  not an array. Sending an array can make the server return `500`.
+- **`update`** -> `update-document` keys the note as **`id`**, not `document_id`.
+  Sending `document_id` returns `400 "Missing document ID"`.
+- **`get`** -> the full single-note record comes from `get-documents-batch`
+  (`{document_ids: [...]}`), not a singular `get-document`.
+
+Full request/response shapes are documented in `docs/granola-api.md` in the companion
+credential-decrypt research repo.

granola_cli-0.1.0/granola/__init__.py

@@ -0,0 +1,61 @@
+"""Granola — decrypt on-disk credentials, auto-refresh, and drive the documented internal API.
+
+Quick start::
+
+    from granola import GranolaClient, notes, sharing
+    client = GranolaClient()
+    me = client.invoke("get-user-info")
+    recent = notes.list_notes(client, limit=10)
+    sharing.add_collaborator(client, "<doc-id>", "person@example.com", name="Person")
+
+Headless / portable auth::
+
+    from granola import GranolaClient, SessionFileSource, Config
+    cfg = Config()
+    client = GranolaClient(cfg, source=SessionFileSource(cfg, "session.json"))
+"""
+from __future__ import annotations
+
+from . import editing, notes, sharing
+from .auth import (
+    RefreshRevoked,
+    format_token_status,
+    refresh_exchange,
+    token_is_expiring,
+)
+from .client import GranolaClient
+from .config import Config
+from .routes import load_routes, resolve_endpoint
+from .sources import (
+    DesktopStoreSource,
+    SessionFileSource,
+    StaticTokenSource,
+    TokenSource,
+    create_session_file,
+    resolve_source,
+)
+from .store import get_dek, read_store, save_store
+
+__version__ = "0.1.0"
+__all__ = [
+    "Config",
+    "GranolaClient",
+    "TokenSource",
+    "DesktopStoreSource",
+    "SessionFileSource",
+    "StaticTokenSource",
+    "resolve_source",
+    "create_session_file",
+    "refresh_exchange",
+    "format_token_status",
+    "token_is_expiring",
+    "RefreshRevoked",
+    "load_routes",
+    "resolve_endpoint",
+    "read_store",
+    "save_store",
+    "get_dek",
+    "notes",
+    "sharing",
+    "editing",
+]

granola_cli-0.1.0/granola/_http.py

@@ -0,0 +1,49 @@
+"""HTTP helpers: base headers + redirect-safe request via httpx."""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import httpx
+
+
+def base_headers(cfg, access_token: str | None = None, additional: dict | None = None) -> dict:
+    headers = {
+        "X-Client-Version": cfg.client_version,
+        "X-Granola-Platform": cfg.platform,
+        "Accept": "application/json",
+        "User-Agent": f"Granola/{cfg.client_version}",
+    }
+    if access_token:
+        headers["Authorization"] = f"Bearer {access_token}"
+    if additional:
+        headers.update(additional)
+    return headers
+
+
+def request(method: str, url: str, *, json_body=None, headers: dict | None = None,
+            timeout: float = 60.0) -> httpx.Response:
+    # follow_redirects=True keeps the POST body across 307/308 (httpx, unlike the
+    # old PowerShell Invoke-RestMethod, does this correctly).
+    with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+        return client.request(method.upper(), url, json=json_body, headers=headers)
+
+
+def granola_running() -> bool:
+    """Best-effort check whether the desktop app is running (Windows/macOS)."""
+    try:
+        if sys.platform == "win32":
+            out = subprocess.run(
+                ["tasklist", "/FI", "IMAGENAME eq Granola.exe", "/NH"],
+                capture_output=True, text=True, timeout=5,
+            )
+            return "Granola.exe" in out.stdout
+        if sys.platform == "darwin":
+            out = subprocess.run(
+                ["/usr/bin/pgrep", "-x", "Granola"],
+                capture_output=True, text=True, timeout=5,
+            )
+            return out.returncode == 0 and bool(out.stdout.strip())
+    except Exception:
+        return False
+    return False

granola_cli-0.1.0/granola/auth.py

@@ -0,0 +1,103 @@
+"""Token primitives: the refresh HTTP exchange, expiry math, account selection,
+and status formatting.
+
+These are deliberately persistence-free. *Where* a refreshed token gets written
+back (the encrypted desktop store vs. a portable session file) lives in
+``sources.py`` — this module only knows how to talk to the refresh endpoint and
+how to reason about a token dict.
+"""
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+from ._http import base_headers, request
+from .config import Config
+
+
+class RefreshRevoked(RuntimeError):
+    """The refresh token was rejected (revoked or already rotated away).
+
+    Carries a source-specific, human-readable recovery message — the desktop and
+    session sources re-raise it with the right re-auth instructions.
+    """
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def token_is_expiring(token: dict, skew_ms: int) -> bool:
+    expiry_ms = int(token["obtained_at"]) + int(token["expires_in"]) * 1000
+    return (expiry_ms - _now_ms()) < skew_ms
+
+
+def select_account(store, email: str | None = None):
+    if email:
+        for acct in store.accounts:
+            if acct.get("email") == email:
+                return acct
+        raise ValueError(f"No stored account with email '{email}'.")
+    return store.accounts[0]
+
+
+def refresh_exchange(cfg: Config, tok: dict) -> dict:
+    """POST the refresh token and return a *new* token dict. Pure — no write-back.
+
+    Raises ``RefreshRevoked`` on 401 (revoked/rotated) and ``RuntimeError`` on any
+    other non-2xx. The returned dict is a copy of ``tok`` with the rotated fields
+    applied, so callers decide where to persist it.
+    """
+    if not tok.get("refresh_token"):
+        raise ValueError("No refresh_token available to refresh.")
+
+    headers = base_headers(cfg, tok["access_token"])
+    resp = request("POST", cfg.refresh_url,
+                   json_body={"refresh_token": tok["refresh_token"]},
+                   headers=headers, timeout=cfg.timeout)
+
+    if resp.status_code == 401:
+        kind = None
+        try:
+            kind = resp.json().get("error")
+        except Exception:
+            pass
+        raise RefreshRevoked(f"Refresh rejected (401{': ' + kind if kind else ''}).")
+    if resp.status_code >= 400:
+        raise RuntimeError(f"Refresh failed: HTTP {resp.status_code}. {resp.text[:300]}")
+
+    data = resp.json()
+    if not data.get("access_token"):
+        raise RuntimeError("Refresh OK but no access_token in response.")
+
+    new = dict(tok)
+    new["access_token"] = data["access_token"]
+    new["expires_in"] = data.get("expires_in", tok.get("expires_in"))
+    for key in ("refresh_token", "token_type", "session_id", "sign_in_method"):
+        if data.get(key):
+            new[key] = data[key]
+    new["obtained_at"] = _now_ms()
+    return new
+
+
+def format_token_status(tok: dict, skew_ms: int, include_secrets: bool = False) -> dict:
+    """A no-secrets status view of one token dict (secrets gated behind the flag)."""
+    obt_ms = int(tok["obtained_at"])
+    obtained = datetime.fromtimestamp(obt_ms / 1000, tz=timezone.utc)
+    expiry = datetime.fromtimestamp(
+        (obt_ms + int(tok["expires_in"]) * 1000) / 1000, tz=timezone.utc
+    )
+    now = datetime.now(timezone.utc)
+    info = {
+        "token_type": tok.get("token_type"),
+        "sign_in_method": tok.get("sign_in_method"),
+        "obtained_at_utc": obtained.isoformat(),
+        "expiry_utc": expiry.isoformat(),
+        "expired": now > expiry,
+        "expiring_soon": token_is_expiring(tok, skew_ms),
+        "minutes_left": round((expiry - now).total_seconds() / 60, 1),
+    }
+    if include_secrets:
+        info["access_token"] = tok.get("access_token")
+        info["refresh_token"] = tok.get("refresh_token")
+    return info