granola-cli 0.1.0__py3-none-any.whl

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/_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/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

granola/cli.py

@@ -0,0 +1,237 @@
+"""`granola` — one CLI for the documented Granola API: credentials + notes + sharing + editing.
+
+Auth:     auth status | auth token | auth refresh | auth export
+Engine:   routes | call
+Read:     notes | get | meta | transcript | panels
+Share:    who | share | unshare | role | share-folder | folder-who | unshare-folder
+Edit:     update | delete
+
+Global auth options (before the command) select the token source:
+  --email EMAIL        pick an account from the local desktop credentials
+  --session PATH       use a refreshable session file
+  --access-token TOK   use this bearer token directly (no refresh)
+  --no-refresh         never auto-refresh
+Environment: GRANOLA_SESSION, GRANOLA_ACCESS_TOKEN.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import editing, notes, sharing
+from .client import GranolaClient
+from .config import Config
+from .routes import load_routes
+from .sources import create_session_file, resolve_source
+
+DEFAULT_SESSION_PATH = Path.home() / ".config" / "granola" / "session.json"
+
+
+def _print(obj) -> None:
+    print(obj if isinstance(obj, str) else json.dumps(obj, indent=2, ensure_ascii=False))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="granola", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--email", help="Select a specific stored desktop account.")
+    p.add_argument("--session", help="Use a refreshable session JSON file.")
+    p.add_argument("--access-token", help="Use this bearer token directly (no refresh).")
+    p.add_argument("--no-refresh", action="store_true", help="Never auto-refresh the token.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # --- auth ---
+    pa = sub.add_parser("auth", help="Token / session management.")
+    asub = pa.add_subparsers(dest="auth_cmd", required=True)
+    pas = asub.add_parser("status", help="Token/account status (no secrets by default).")
+    pas.add_argument("--include-secrets", action="store_true")
+    asub.add_parser("token", help="Print the current valid bearer token.")
+    asub.add_parser("refresh", help="Force-refresh the selected source.")
+    pae = asub.add_parser("export", help="Write a refreshable session file from desktop creds.")
+    pae.add_argument("path", nargs="?", default=None,
+                     help=f"Destination (default: {DEFAULT_SESSION_PATH}).")
+    pae.add_argument("--no-refresh-token", action="store_true",
+                     help="Bearer-only session (cannot refresh; for short-lived/CI use).")
+
+    # --- engine ---
+    pr = sub.add_parser("routes", help="List endpoint routes (optional filter).")
+    pr.add_argument("filter", nargs="?", default="")
+    pc = sub.add_parser("call", help="Call any endpoint by name or URL.")
+    pc.add_argument("endpoint")
+    pc.add_argument("--body", help='JSON body, e.g. \'{"limit":5}\'.')
+    pc.add_argument("--method", default="POST")
+    pc.add_argument("--raw", action="store_true")
+
+    # --- read ---
+    pn = sub.add_parser("notes", help="List recent notes.")
+    pn.add_argument("--limit", type=int, default=20)
+    pn.add_argument("--json", action="store_true")
+    pg = sub.add_parser("get", help="Full record for one note.")
+    pg.add_argument("id")
+    pg.add_argument("--json", action="store_true")
+    pm = sub.add_parser("meta", help="Creator/attendees/conferencing for a note.")
+    pm.add_argument("id")
+    pt = sub.add_parser("transcript", help="Transcript as markdown.")
+    pt.add_argument("id")
+    pp = sub.add_parser("panels", help="AI summary panels for a note.")
+    pp.add_argument("id")
+    pp.add_argument("--json", action="store_true")
+
+    # --- share ---
+    pw = sub.add_parser("who", help="Who has access to a note.")
+    pw.add_argument("id")
+    ps = sub.add_parser("share", help="Add a collaborator to a note.")
+    ps.add_argument("id")
+    ps.add_argument("--email", required=True)
+    ps.add_argument("--name")
+    ps.add_argument("--role", default="collaborator")
+    pu = sub.add_parser("unshare", help="Remove a collaborator from a note.")
+    pu.add_argument("id")
+    pu.add_argument("--email", required=True)
+    pu.add_argument("--cleanup-list", action="append", default=[],
+                    help="Also strip inherited access from this folder id (repeatable).")
+    prole = sub.add_parser("role", help="Change a collaborator's role.")
+    prole.add_argument("id")
+    prole.add_argument("--user", required=True, help="user_id (from `who`).")
+    prole.add_argument("--role", required=True)
+    pf = sub.add_parser("share-folder", help="Share a folder with someone (folder-level access).")
+    pf.add_argument("folder", help='Folder id or name (e.g. "Team Notes").')
+    pf.add_argument("--email", required=True)
+    pf.add_argument("--name")
+    pf.add_argument("--role", default="collaborator")
+    pf.add_argument("--per-note", action="store_true",
+                    help="Add to each note directly (invites non-Granola emails; vs one-call folder ACL).")
+    pf.add_argument("--include-existing", action="store_true",
+                    help="(per-note) Re-add even where the person already has access.")
+    pfw = sub.add_parser("folder-who", help="Who has access to a folder.")
+    pfw.add_argument("folder")
+    puf = sub.add_parser("unshare-folder", help="Revoke a person's folder-level access.")
+    puf.add_argument("folder")
+    puf.add_argument("--email", required=True)
+
+    # --- edit ---
+    pup = sub.add_parser("update", help="Partial-edit a note (title/markdown).")
+    pup.add_argument("id")
+    pup.add_argument("--title")
+    pup.add_argument("--markdown")
+    pd = sub.add_parser("delete", help="PERMANENTLY hard-delete a note.")
+    pd.add_argument("id")
+    pd.add_argument("--yes", action="store_true", help="Required: confirm.")
+    return p
+
+
+def main(argv=None) -> int:  # noqa: C901 - flat dispatch is clearer than abstraction here
+    try:  # Windows console defaults to cp1252; note content is UTF-8 (emoji, smart quotes)
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+    args = build_parser().parse_args(argv)
+    cfg = Config()
+    c = args.cmd
+
+    # auth export reads the desktop store directly; it doesn't use the resolved source.
+    if c == "auth" and args.auth_cmd == "export":
+        if args.session or args.access_token:
+            print("auth export reads the desktop credential store; "
+                  "don't pass --session/--access-token.", file=sys.stderr)
+            return 2
+        dest = args.path or str(DEFAULT_SESSION_PATH)
+        out = create_session_file(cfg, dest, email=args.email,
+                                  include_refresh_token=not args.no_refresh_token)
+        mode = "owner-only" if sys.platform == "win32" else "0600"
+        kind = "bearer-only" if args.no_refresh_token else "refreshable"
+        print(f"Wrote {kind} session file: {out} (mode {mode})", file=sys.stderr)
+        print(out)
+        return 0
+
+    source = resolve_source(cfg, email=args.email, session=args.session,
+                            access_token=args.access_token, no_refresh=args.no_refresh)
+    client = GranolaClient(cfg, source=source)
+
+    # auth
+    if c == "auth":
+        if args.auth_cmd == "status":
+            _print(source.status(include_secrets=args.include_secrets))
+        elif args.auth_cmd == "token":
+            print(source.access_token())
+        elif args.auth_cmd == "refresh":
+            source.access_token(force=True)
+            _print(source.status(include_secrets=False))
+
+    # engine
+    elif c == "routes":
+        for name in sorted(load_routes(cfg)):
+            if args.filter in name:
+                print(f"{name:40} {load_routes(cfg)[name]}")
+    elif c == "call":
+        body = json.loads(args.body) if args.body else None
+        _print(client.invoke(args.endpoint, body=body, method=args.method, raw=args.raw))
+
+    # read
+    elif c == "notes":
+        docs = notes.list_notes(client, limit=args.limit)
+        if args.json:
+            _print(docs)
+        else:
+            for d in docs:
+                print(f"{d.get('id')}  {d.get('updated_at','')[:19]:19}  {d.get('title') or '(untitled)'}")
+            print(f"{len(docs)} notes", file=sys.stderr)
+    elif c == "get":
+        rec = notes.get_note(client, args.id)
+        if not rec:
+            print("note not found", file=sys.stderr)
+            return 1
+        if args.json:
+            _print(rec)
+        else:
+            for k in ("id", "title", "created_at", "updated_at", "workspace_id",
+                      "public", "visibility", "document_user_role", "is_shared_direct"):
+                print(f"{k:20} {rec.get(k)}")
+    elif c == "meta":
+        _print(notes.get_metadata(client, args.id))
+    elif c == "transcript":
+        print(notes.transcript_to_markdown(notes.get_transcript(client, args.id)))
+    elif c == "panels":
+        _print(notes.get_panels(client, args.id))
+
+    # share
+    elif c == "who":
+        for u in sharing.list_collaborators(client, args.id):
+            print(f"{u.get('role',''):13} {u.get('email',''):35} {u.get('user_id','')}")
+    elif c == "share":
+        _print(sharing.add_collaborator(client, args.id, args.email, name=args.name, role=args.role))
+    elif c == "unshare":
+        _print(sharing.remove_collaborator(client, args.id, args.email,
+                                           cleanup_list_ids=args.cleanup_list or None))
+    elif c == "role":
+        _print(sharing.set_role(client, args.id, args.user, args.role))
+    elif c == "share-folder":
+        _print(sharing.share_folder(client, args.folder, args.email, name=args.name,
+                                    role=args.role, per_note=args.per_note,
+                                    skip_existing=not args.include_existing))
+    elif c == "folder-who":
+        for u in sharing.list_folder_collaborators(client, args.folder):
+            print(f"{u.get('role',''):13} {u.get('email',''):35} {u.get('access_source','')}")
+    elif c == "unshare-folder":
+        _print(sharing.unshare_folder(client, args.folder, args.email))
+
+    # edit
+    elif c == "update":
+        fields = {k: v for k, v in (("title", args.title), ("notes_markdown", args.markdown)) if v is not None}
+        if not fields:
+            print("nothing to update (pass --title and/or --markdown)", file=sys.stderr)
+            return 2
+        _print(editing.update_note(client, args.id, **fields))
+    elif c == "delete":
+        if not args.yes:
+            print("refusing to hard-delete without --yes (this is permanent)", file=sys.stderr)
+            return 2
+        _print(editing.delete_note(client, args.id))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

granola/client.py

@@ -0,0 +1,46 @@
+"""High-level Granola API client."""
+from __future__ import annotations
+
+from ._http import base_headers, request
+from .config import Config
+from .routes import resolve_endpoint
+from .sources import DesktopStoreSource, TokenSource
+
+
+class GranolaClient:
+    """Call Granola API endpoints with a bearer token from a ``TokenSource``.
+
+    The source (desktop store, session file, or static token) is resolved once and
+    handles its own refresh + write-back, so call sites stay auth-agnostic.
+
+    >>> c = GranolaClient()                       # defaults to the desktop store
+    >>> c.invoke("get-user-info")
+    >>> c.invoke("get-documents", body={"limit": 10})
+    """
+
+    def __init__(self, cfg: Config | None = None, source: TokenSource | None = None):
+        self.cfg = cfg or Config()
+        self.source = source or DesktopStoreSource(self.cfg)
+
+    def access_token(self, force: bool = False) -> str:
+        return self.source.access_token(force=force)
+
+    def resolve(self, endpoint: str) -> str:
+        return resolve_endpoint(endpoint, self.cfg)
+
+    def invoke(self, endpoint: str, body=None, method: str = "POST",
+               additional_headers: dict | None = None, raw: bool = False):
+        token = self.source.access_token()
+        url = self.resolve(endpoint)
+        headers = base_headers(self.cfg, token, additional_headers)
+        resp = request(method, url, json_body=body, headers=headers, timeout=self.cfg.timeout)
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Granola API '{endpoint}' returned HTTP {resp.status_code}. {resp.text[:500]}"
+            )
+        if raw:
+            return resp.text
+        try:
+            return resp.json()
+        except Exception:
+            return resp.text

granola/config.py

@@ -0,0 +1,48 @@
+"""Configuration for the Granola API engine."""
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _default_granola_dir() -> Path:
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Granola"
+    appdata = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+    return Path(appdata) / "Granola"
+
+
+def _default_app_root() -> Path:
+    if sys.platform == "darwin":
+        return Path("/Applications/Granola.app/Contents")
+    local = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    return Path(local) / "Programs" / "@granolaelectron"
+
+
+@dataclass
+class Config:
+    """Resolves paths and constants for one Granola profile.
+
+    For a *headless second session* (Option B), point ``granola_dir`` at the
+    second OS user's ``%APPDATA%\\Granola`` (the process must run as that user so
+    DPAPI CurrentUser can unseal the key).
+    """
+
+    granola_dir: Path = field(default_factory=_default_granola_dir)
+    app_root: Path = field(default_factory=_default_app_root)
+    client_version: str = "7.303.0"          # app.asar package.json version
+    # X-Granola-Platform (darwin -> macOS, win32 -> Windows)
+    platform: str = field(
+        default_factory=lambda: "macOS" if sys.platform == "darwin" else "Windows")
+    refresh_url: str = "https://api.granola.ai/v1/refresh-access-token"
+    refresh_skew_ms: int = 120_000           # app refreshes when <2 min to expiry
+    timeout: float = 60.0
+    routes_path: Path | None = None
+
+    def __post_init__(self) -> None:
+        self.granola_dir = Path(self.granola_dir)
+        self.app_root = Path(self.app_root)
+        if self.routes_path is not None:
+            self.routes_path = Path(self.routes_path)

granola/crypto.py

@@ -0,0 +1,117 @@
+"""Windows DPAPI unseal + AES-256-GCM (clean, via the `cryptography` lib).
+
+DPAPI uses a tiny ctypes shim against crypt32.dll so the only third-party
+dependency is `cryptography` (no pywin32). DPAPI is inherently Windows + same
+Windows user (CurrentUser scope); everything above the access token is portable.
+"""
+from __future__ import annotations
+
+import ctypes
+import hashlib
+import os
+import subprocess
+import sys
+from ctypes import wintypes
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+def dpapi_unprotect(blob: bytes) -> bytes:
+    """Decrypt a Windows DPAPI blob under the CurrentUser scope."""
+    if sys.platform != "win32":
+        raise RuntimeError("DPAPI decryption is only available on Windows.")
+
+    class DATA_BLOB(ctypes.Structure):
+        _fields_ = [("cbData", wintypes.DWORD),
+                    ("pbData", ctypes.POINTER(ctypes.c_byte))]
+
+    buf_in = ctypes.create_string_buffer(bytes(blob), len(blob))
+    blob_in = DATA_BLOB(len(blob), ctypes.cast(buf_in, ctypes.POINTER(ctypes.c_byte)))
+    blob_out = DATA_BLOB()
+
+    crypt32 = ctypes.WinDLL("crypt32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    ok = crypt32.CryptUnprotectData(
+        ctypes.byref(blob_in), None, None, None, None, 0, ctypes.byref(blob_out)
+    )
+    if not ok:
+        raise ctypes.WinError(ctypes.get_last_error())
+    try:
+        return ctypes.string_at(blob_out.pbData, blob_out.cbData)
+    finally:
+        kernel32.LocalFree(blob_out.pbData)
+
+
+def aes_gcm_decrypt(blob: bytes, key: bytes, prefix_len: int = 0, iv_len: int = 12) -> bytes:
+    """Decrypt a `[prefix?] + IV(12) + ciphertext + tag(16)` blob.
+
+    `cryptography` expects the GCM tag appended to the ciphertext, which is
+    exactly Granola's on-disk layout after the IV.
+    """
+    nonce = blob[prefix_len:prefix_len + iv_len]
+    ct_and_tag = blob[prefix_len + iv_len:]
+    return AESGCM(key).decrypt(nonce, ct_and_tag, None)
+
+
+def aes_gcm_encrypt(plaintext: bytes, key: bytes, iv_len: int = 12) -> bytes:
+    """Produce `IV(12) + ciphertext + tag(16)`, matching Granola's `.enc` layout."""
+    nonce = os.urandom(iv_len)
+    return nonce + AESGCM(key).encrypt(nonce, plaintext, None)
+
+
+# --- macOS safeStorage (Keychain-backed) ---------------------------------------
+# On macOS, Granola's `storage.dek` is wrapped with Electron/Chromium safeStorage
+# (AES-128-CBC, key derived from a Keychain password) instead of Windows DPAPI.
+# Scheme + behavior verified against harperreed/muesli's session_decrypt.rs.
+
+KEYCHAIN_SERVICE = "Granola Safe Storage"
+KEYCHAIN_ACCOUNT = "Granola Key"
+_SAFE_STORAGE_SALT = b"saltysalt"
+_SAFE_STORAGE_ITERATIONS = 1003
+_SAFE_STORAGE_KEY_LEN = 16
+_SAFE_STORAGE_IV = b" " * 16
+
+
+def keychain_password(service: str = KEYCHAIN_SERVICE, account: str = KEYCHAIN_ACCOUNT) -> str:
+    """Read Granola's safeStorage key from the macOS login Keychain.
+
+    Shells out to ``/usr/bin/security`` (no extra deps). The first call may trigger
+    a Keychain access prompt unless this binary is already trusted for the item.
+    """
+    if sys.platform != "darwin":
+        raise RuntimeError("Keychain access is only available on macOS.")
+    try:
+        out = subprocess.run(
+            ["/usr/bin/security", "find-generic-password", "-s", service, "-a", account, "-w"],
+            capture_output=True, text=True, timeout=20,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError("`security` tool not found (macOS only).") from exc
+    if out.returncode != 0:
+        raise RuntimeError(
+            f"Keychain item '{service}'/'{account}' not found or access denied: "
+            f"{out.stderr.strip() or out.returncode}"
+        )
+    return out.stdout.strip("\n")
+
+
+def aes_128_cbc_safestorage_decrypt(blob: bytes, password: str, prefix: bytes = b"v10") -> bytes:
+    """Decrypt an Electron/Chromium safeStorage ``v10`` blob (macOS/Linux scheme).
+
+    Key = PBKDF2-HMAC-SHA1(password, "saltysalt", 1003, 16 bytes); AES-128-CBC with a
+    16-space IV and PKCS#7 padding. Used for ``storage.dek`` on macOS.
+    """
+    if blob[: len(prefix)] != prefix:
+        raise ValueError(f"safeStorage blob missing {prefix!r} prefix.")
+    ciphertext = blob[len(prefix):]
+    key = hashlib.pbkdf2_hmac(
+        "sha1", password.encode("utf-8"), _SAFE_STORAGE_SALT,
+        _SAFE_STORAGE_ITERATIONS, dklen=_SAFE_STORAGE_KEY_LEN,
+    )
+    dec = Cipher(algorithms.AES(key), modes.CBC(_SAFE_STORAGE_IV)).decryptor()
+    padded = dec.update(ciphertext) + dec.finalize()
+    pad = padded[-1] if padded else 0
+    if not 1 <= pad <= 16 or pad > len(padded):
+        raise ValueError("Bad PKCS#7 padding (wrong Keychain password?).")
+    return padded[:-pad]