telegram-kit 0.1.2__tar.gz

telegram_kit-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUTF8: "1"
+
+jobs:
+  test:
+    name: Python 3.10 / ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+      - name: Lint
+        run: uv run ruff check .
+      - name: Test
+        run: uv run python -m unittest discover -s tests -t . -v
+      - name: Build distributions
+        run: uv build --wheel
+      - name: Validate wheel is importable standalone
+        shell: python
+        run: |
+          import os
+          import pathlib
+          import subprocess
+          import tempfile
+
+          wheel, = pathlib.Path("dist").glob("*.whl")
+          with tempfile.TemporaryDirectory() as directory:
+              environment = pathlib.Path(directory)
+              subprocess.run(["uv", "venv", environment], check=True)
+              scripts = environment / ("Scripts" if os.name == "nt" else "bin")
+              python = scripts / ("python.exe" if os.name == "nt" else "python")
+              subprocess.run(
+                  ["uv", "pip", "install", "--python", python, "--no-index", wheel],
+                  check=True,
+              )
+              subprocess.run([python, "-I", "-c", "import telegram_kit"], check=True)
+              print("telegram_kit imports standalone OK")
+
+  # Failure-only pager. A green run sends nothing on purpose: a notification
+  # that arrives on every push is one nobody reads. Credentials live in repo
+  # secrets, never in this file — see README "CI notifications" for the two
+  # `gh secret set` commands that configure them.
+  notify-telegram:
+    needs: test
+    if: ${{ failure() && github.event_name == 'push' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Notify Telegram
+        env:
+          TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
+        run: |
+          # Unconfigured secrets are a valid state (a fork, or a clone whose
+          # owner never set them up). Skip quietly instead of failing the job
+          # and reporting a second, misleading red X on top of the real one.
+          if [ -z "$TOKEN" ] || [ -z "$CHAT_ID" ]; then
+            echo "::notice::TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID not set — skipping notification"
+            exit 0
+          fi
+          # parse_mode=HTML: a branch or commit subject containing < & > would
+          # otherwise produce unparseable markup and Telegram would 400.
+          esc() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'; }
+          ci_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          message="🚨 <b>CI failed</b>
+
+          <b>Repository:</b> <code>$(esc "$GITHUB_REPOSITORY")</code>
+          <b>Branch:</b> <code>$(esc "$GITHUB_REF_NAME")</code>
+          <b>Commit:</b> <code>$(esc "${GITHUB_SHA::7}")</code>
+
+          <a href=\"$ci_url\">Open failed CI run</a>"
+          curl --fail --silent --show-error --max-time 30 \
+            --data-urlencode "chat_id=$CHAT_ID" \
+            --data-urlencode "parse_mode=HTML" \
+            --data-urlencode "disable_web_page_preview=true" \
+            --data-urlencode "text=$message" \
+            "https://api.telegram.org/bot$TOKEN/sendMessage"

telegram_kit-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish
+
+# GitHub Releases are created by the /release script; this job only uploads to PyPI.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish-${{ github.ref }}
+
+env:
+  PYTHONUTF8: "1"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+      - name: Check, test, and build
+        run: |
+          uv run ruff check .
+          uv run python -m unittest discover -s tests -t .
+          uv build
+      - name: Validate wheel version matches tag
+        run: |
+          uv venv .release-venv
+          uv pip install --python .release-venv/bin/python --no-index dist/*.whl
+          reported="$(.release-venv/bin/python -I -c 'import importlib.metadata as m; print(m.version("telegram-kit"))')"
+          if [ "$reported" != "${GITHUB_REF_NAME#v}" ]; then
+            echo "::error::wheel reports '$reported', expected '${GITHUB_REF_NAME#v}'"
+            exit 1
+          fi
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

telegram_kit-0.1.2/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.ruff_cache/
+.coverage

telegram_kit-0.1.2/CHANGELOG.md

@@ -0,0 +1,31 @@
+## [0.1.2] - 2026-09-26
+
+### 🐛 Bug Fixes
+
+- **tests:** Stop wiping env vars Windows needs to boot Python
+
+### 📚 Documentation
+
+- **readme:** Document PyPI install alongside git-tag pin
+
+### ⚙️ Miscellaneous Tasks
+
+- **publish:** Add PyPI publish workflow on v* tags
+## [0.1.1] - 2026-09-26
+
+### 📚 Documentation
+
+- Document CI Telegram notification setup
+
+### 🧪 Testing
+
+- Cover every branch of the credential store and writer
+
+### ⚙️ Miscellaneous Tasks
+
+- Add python tooling and CI
+## [0.1.0] - 2026-09-26
+
+### 🚀 Features
+
+- Extract telegram_kit as a standalone package

telegram_kit-0.1.2/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Wes Kao
+
+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 OF THE SOFTWARE.

telegram_kit-0.1.2/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: telegram-kit
+Version: 0.1.2
+Summary: Secure Telegram Bot API notifications for any Python project. Stdlib only.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# telegram-kit
+
+Secure Telegram Bot API notifications for any Python project. Stdlib only —
+no dependencies, no vendoring.
+
+```python
+import telegram_kit
+
+telegram_kit.notify("build finished", service="my-app", chat_id="123456789")
+
+store = telegram_kit.CredentialStore("my-app")
+token = telegram_kit.read_hidden("Telegram bot token (hidden): ")
+if token and store.set("telegram_bot_token", token):
+    print("stored as", telegram_kit.mask_secret(token))
+```
+
+## Install
+
+```bash
+uv add "telegram-kit>=0.1.2,<0.2"
+```
+
+Published to PyPI on every `v*` tag (`.github/workflows/publish.yml`).
+`uv lock --upgrade-package telegram-kit` is how every project using this kit
+picks up a fix — no file to copy, no diff to reapply. A project that is never
+published to PyPI can pin the git tag instead:
+`uv add "telegram-kit @ git+https://github.com/weskao/telegram-kit@v0.1.2"`.
+
+## What it guarantees, whichever project uses it
+
+- **No plaintext fallback.** `CredentialStore` writes to the OS credential
+  store (macOS Keychain, Linux Secret Service, Windows DPAPI). With none
+  available, it refuses to store rather than falling back to a plaintext
+  file or home-rolled obfuscation.
+- **Each caller gets its own namespace.** `CredentialStore(service)` keys
+  every item under that service name, so two projects on the same machine
+  never collide.
+- **Credentials never touch argv or the process list** — batch-mode/stdin
+  paths are used for every backend.
+- **Owner-only atomic writes** (`write_private`) for anything that must live
+  on disk, on POSIX and Windows alike.
+
+## API
+
+| Function | Purpose |
+|---|---|
+| `CredentialStore(service, dpapi_dir=None)` | Get/set/delete a secret in the OS store. |
+| `resolve_credentials(token, chat_id, environ=None)` | Configured value, else `TG_BOT_TOKEN`/`TG_CHAT_ID`. |
+| `send_message(token, chat_id, text, timeout=10)` | One `sendMessage` call. `False` on any failure. |
+| `notify(text, service, chat_id="", token_key=..., store=None)` | Resolve + send in one call. |
+| `read_hidden(prompt, ask=None)` | Hidden input; `None` if the terminal can't hide it. |
+| `mask_secret(secret)` | `********` plus at most the last 4 characters. |
+| `write_private(target, content)` | Atomic, owner-only file write. |
+
+## Develop
+
+```bash
+uv run python -m unittest discover -s tests -t . -v
+uv run ruff check .
+```
+
+## CI notifications
+
+`.github/workflows/ci.yml` runs the test matrix (macOS/Linux/Windows) on every push and PR,
+then a separate `notify-telegram` job sends a Telegram message only when the test job fails on
+a `push` (never on green runs, never on `pull_request`, to avoid pinging on forks/external PRs).
+Configure it once per repo:
+
+```bash
+gh secret set TELEGRAM_BOT_TOKEN
+gh secret set TELEGRAM_CHAT_ID
+```
+
+Unconfigured secrets are a valid state — the job skips quietly instead of failing a second time
+on top of the real failure.

telegram_kit-0.1.2/README.md

@@ -0,0 +1,75 @@
+# telegram-kit
+
+Secure Telegram Bot API notifications for any Python project. Stdlib only —
+no dependencies, no vendoring.
+
+```python
+import telegram_kit
+
+telegram_kit.notify("build finished", service="my-app", chat_id="123456789")
+
+store = telegram_kit.CredentialStore("my-app")
+token = telegram_kit.read_hidden("Telegram bot token (hidden): ")
+if token and store.set("telegram_bot_token", token):
+    print("stored as", telegram_kit.mask_secret(token))
+```
+
+## Install
+
+```bash
+uv add "telegram-kit>=0.1.2,<0.2"
+```
+
+Published to PyPI on every `v*` tag (`.github/workflows/publish.yml`).
+`uv lock --upgrade-package telegram-kit` is how every project using this kit
+picks up a fix — no file to copy, no diff to reapply. A project that is never
+published to PyPI can pin the git tag instead:
+`uv add "telegram-kit @ git+https://github.com/weskao/telegram-kit@v0.1.2"`.
+
+## What it guarantees, whichever project uses it
+
+- **No plaintext fallback.** `CredentialStore` writes to the OS credential
+  store (macOS Keychain, Linux Secret Service, Windows DPAPI). With none
+  available, it refuses to store rather than falling back to a plaintext
+  file or home-rolled obfuscation.
+- **Each caller gets its own namespace.** `CredentialStore(service)` keys
+  every item under that service name, so two projects on the same machine
+  never collide.
+- **Credentials never touch argv or the process list** — batch-mode/stdin
+  paths are used for every backend.
+- **Owner-only atomic writes** (`write_private`) for anything that must live
+  on disk, on POSIX and Windows alike.
+
+## API
+
+| Function | Purpose |
+|---|---|
+| `CredentialStore(service, dpapi_dir=None)` | Get/set/delete a secret in the OS store. |
+| `resolve_credentials(token, chat_id, environ=None)` | Configured value, else `TG_BOT_TOKEN`/`TG_CHAT_ID`. |
+| `send_message(token, chat_id, text, timeout=10)` | One `sendMessage` call. `False` on any failure. |
+| `notify(text, service, chat_id="", token_key=..., store=None)` | Resolve + send in one call. |
+| `read_hidden(prompt, ask=None)` | Hidden input; `None` if the terminal can't hide it. |
+| `mask_secret(secret)` | `********` plus at most the last 4 characters. |
+| `write_private(target, content)` | Atomic, owner-only file write. |
+
+## Develop
+
+```bash
+uv run python -m unittest discover -s tests -t . -v
+uv run ruff check .
+```
+
+## CI notifications
+
+`.github/workflows/ci.yml` runs the test matrix (macOS/Linux/Windows) on every push and PR,
+then a separate `notify-telegram` job sends a Telegram message only when the test job fails on
+a `push` (never on green runs, never on `pull_request`, to avoid pinging on forks/external PRs).
+Configure it once per repo:
+
+```bash
+gh secret set TELEGRAM_BOT_TOKEN
+gh secret set TELEGRAM_CHAT_ID
+```
+
+Unconfigured secrets are a valid state — the job skips quietly instead of failing a second time
+on top of the real failure.

telegram_kit-0.1.2/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "telegram-kit"
+version = "0.1.2"
+description = "Secure Telegram Bot API notifications for any Python project. Stdlib only."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/telegram_kit"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.21",
+]

telegram_kit-0.1.2/src/telegram_kit/__init__.py

@@ -0,0 +1,366 @@
+"""Secure Telegram notifications for any Python project. Stdlib only.
+
+``pip``/``uv`` install this repository and ``import telegram_kit`` — it has no
+dependency on the ``codex_reset_watch`` CLI, so importing it is cheap.
+
+    import telegram_kit
+
+    telegram_kit.notify("build finished", service="my-app", chat_id="123456789")
+
+    store = telegram_kit.CredentialStore("my-app")
+    token = telegram_kit.read_hidden("Telegram bot token (hidden): ")
+    if token and store.set("telegram_bot_token", token):
+        print("stored as", telegram_kit.mask_secret(token))
+
+What it guarantees, whichever project uses it:
+
+* The bot token lives only in the OS credential store, namespaced by
+  *service*: macOS Keychain (``security``), Linux Secret Service
+  (``secret-tool``) or Windows DPAPI (PowerShell). With none available,
+  nothing is stored; there is no plaintext or obfuscated fallback.
+* The secret never enters an argument vector (``ps``, shell history): every
+  helper receives it on stdin.
+* Reads never raise. A locked keyring or missing helper just means "no secret".
+* ``TG_BOT_TOKEN`` / ``TG_CHAT_ID`` are fallbacks for values the caller did
+  not configure, each on its own.
+
+Passing ``service="codex-reset-watch"`` reuses the token that ``crw config``
+stored. The chat id is ordinary configuration, so each project keeps its own.
+"""
+from __future__ import annotations
+
+import contextlib
+import functools
+import getpass
+import http.client
+import json
+import os
+import pathlib
+import platform
+import re
+import shutil
+import subprocess
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+import warnings
+from collections.abc import Callable, Mapping
+
+IS_MACOS = platform.system() == "Darwin"
+IS_WINDOWS = platform.system() == "Windows"
+
+#: How long a credential helper may take before we give up on it.
+TIMEOUT_SECONDS = 10
+
+#: Environment variables that stand in for credentials the caller did not set.
+TOKEN_ENV, CHAT_ID_ENV = "TG_BOT_TOKEN", "TG_CHAT_ID"
+TOKEN_KEY = "telegram_bot_token"
+
+BACKEND_LABELS = {
+    "keychain": "macOS Keychain",
+    "libsecret": "Secret Service (libsecret)",
+    "dpapi": "Windows DPAPI",
+}
+
+_API = "https://api.telegram.org/bot{token}/sendMessage"
+
+
+# ── owner-only files ─────────────────────────────────────────────────────────
+
+def write_private(target: pathlib.Path, content: str) -> None:
+    """Atomically write owner-only text; fail before writing if protection fails."""
+    target = pathlib.Path(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.is_symlink():
+        raise OSError("Refusing to overwrite a symlink")
+    temporary = target.with_name(f".{target.name}.{uuid.uuid4().hex}.tmp")
+    created = False
+    try:
+        if os.name == "nt":
+            # The ACL is attached at creation, before content is written.
+            # The path and content travel on stdin, never the command line.
+            script = (
+                "$ErrorActionPreference='Stop'; "
+                "$data=[Console]::In.ReadToEnd() | ConvertFrom-Json; "
+                "$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User; "
+                "$acl=[Security.AccessControl.FileSecurity]::new(); "
+                "$acl.SetAccessRuleProtection($true,$false); $acl.SetOwner($sid); "
+                "$rule=[Security.AccessControl.FileSystemAccessRule]::new($sid,"
+                "[Security.AccessControl.FileSystemRights]::FullControl,"
+                "[Security.AccessControl.AccessControlType]::Allow); "
+                "$acl.AddAccessRule($rule); "
+                "$file=[IO.FileStream]::new($data.path,[IO.FileMode]::CreateNew,"
+                "[Security.AccessControl.FileSystemRights]::FullControl,[IO.FileShare]::None,4096,"
+                "[IO.FileOptions]::None,$acl); "
+                "$writer=[IO.StreamWriter]::new($file,[Text.UTF8Encoding]::new($false)); "
+                "try { $writer.Write($data.content) } finally { $writer.Dispose() }"
+            )
+            created = True  # PowerShell may create it before failing or timing out
+            try:
+                result = subprocess.run(
+                    ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script],
+                    input=json.dumps({"path": str(temporary), "content": content}, ensure_ascii=True),
+                    capture_output=True, text=True, timeout=15, check=False,
+                )
+            except subprocess.SubprocessError as exc:
+                raise OSError("Unable to create an owner-only file") from exc
+            if result.returncode:
+                raise OSError("Unable to create an owner-only file")
+        else:
+            fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            created = True
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                stream.write(content)
+        os.replace(temporary, target)
+        created = False
+    finally:
+        if created:
+            temporary.unlink(missing_ok=True)
+
+
+# ── credential store ─────────────────────────────────────────────────────────
+
+def _run(argv, stdin: str | None = None) -> tuple[int, str]:
+    """The single subprocess funnel: ``(returncode, stdout)``.
+
+    Tests replace this whole function, so nothing above it needs a keychain.
+    """
+    completed = subprocess.run(
+        list(argv), input=stdin, capture_output=True, text=True,
+        timeout=TIMEOUT_SECONDS, check=False,
+    )
+    return completed.returncode, completed.stdout
+
+
+def _unhex(secret: str) -> str:
+    """Undo the hex encoding ``security -w`` applies to "non-clean" secrets.
+
+    It decides that per item, so the shape of the output is the only signal.
+    A secret that is itself pure hex stays as-is unless it also decodes to
+    valid UTF-8 — Telegram tokens contain ``:`` so they never take that path.
+    """
+    if not re.fullmatch(r"(?:[0-9a-fA-F]{2})+", secret):
+        return secret
+    try:
+        return bytes.fromhex(secret).decode("utf-8")
+    except (ValueError, UnicodeDecodeError):
+        return secret
+
+
+def _batch_quote(value: str) -> str:
+    """Escape a value for a double-quoted argument in ``security -i`` batch mode.
+
+    Rejects newlines outright: batch mode is line-oriented, so an embedded one
+    would end the command and let the rest be read as a second one.
+    """
+    if "\n" in value or "\r" in value:
+        raise ValueError("security batch argument contains a newline")
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _detect_backend() -> str | None:
+    if IS_MACOS and shutil.which("security"):
+        return "keychain"
+    if IS_WINDOWS and shutil.which("powershell.exe"):
+        return "dpapi"
+    if shutil.which("secret-tool"):
+        return "libsecret"
+    return None
+
+
+@functools.lru_cache(maxsize=1)
+def backend() -> str | None:
+    """Which credential store this machine has, or ``None``. Probed once."""
+    return _detect_backend()
+
+
+def available() -> bool:
+    return backend() is not None
+
+
+def backend_label() -> str:
+    """A human name for the active store, for ``doctor`` and the config menu."""
+    return BACKEND_LABELS.get(backend() or "", "none")
+
+
+def legacy_windows_env_token_present() -> bool:
+    """Detect a token left by older `setx` installs without reading it aloud."""
+    if not IS_WINDOWS:
+        return False
+    try:
+        import winreg
+        with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as key:
+            value, _ = winreg.QueryValueEx(key, "TG_BOT_TOKEN")
+            return bool(value)
+    except OSError:
+        return False
+
+
+def _default_dpapi_dir(service: str) -> pathlib.Path:
+    base = os.environ.get("APPDATA") or str(pathlib.Path.home() / "AppData" / "Roaming")
+    return pathlib.Path(base) / service
+
+
+class CredentialStore:
+    """The OS credential store, scoped to one *service* name.
+
+    *dpapi_dir* returns the folder for Windows DPAPI ciphertext files. It is a
+    callable so a caller whose config folder can move (an env override) is
+    asked each time rather than once.
+    """
+
+    def __init__(self, service: str,
+                 dpapi_dir: Callable[[], pathlib.Path] | None = None) -> None:
+        self.service = service
+        self._dpapi_dir = dpapi_dir or (lambda: _default_dpapi_dir(service))
+
+    def _dpapi_path(self, key: str) -> pathlib.Path:
+        if not re.fullmatch(r"[A-Za-z0-9_-]+", key):
+            raise ValueError("Invalid credential identifier")
+        return pathlib.Path(self._dpapi_dir()) / f"{key}.dpapi"
+
+    def get(self, key: str) -> str:
+        """The stored secret for *key*, or ``""`` when there is none.
+
+        Never raises: a locked keyring, a missing helper or a denied prompt all
+        mean "no secret", which the caller already handles.
+        """
+        active = backend()
+        if active is None:
+            return ""
+        with contextlib.suppress(Exception):
+            if active == "keychain":
+                code, out = _run(["security", "find-generic-password",
+                                  "-s", self.service, "-a", key, "-w"])
+                if code == 0:
+                    return _unhex(out.strip())
+            elif active == "libsecret":
+                code, out = _run(["secret-tool", "lookup", "service", self.service, "account", key])
+            else:  # dpapi
+                path = self._dpapi_path(key)
+                if not path.exists():
+                    return ""
+                code, out = _run([
+                    "powershell.exe", "-NoProfile", "-NonInteractive", "-Command",
+                    ("$s = [Console]::In.ReadToEnd().Trim() | ConvertTo-SecureString; "
+                     "[Runtime.InteropServices.Marshal]::PtrToStringAuto("
+                     "[Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))"),
+                ], stdin=path.read_text(encoding="utf-8"))
+            if code == 0:
+                return out.strip()
+        return ""
+
+    def set(self, key: str, value: str) -> bool:
+        """Store *value* for *key*. ``False`` when it could not be stored securely.
+
+        An empty *value* deletes the item instead of storing a blank — that is how
+        the menu clears a token.
+        """
+        if not value:
+            return self.delete(key)
+        active = backend()
+        if active is None:
+            return False  # refuse rather than write plaintext; see the module docstring
+        with contextlib.suppress(Exception):
+            if active == "keychain":
+                # `add-generic-password -w` with no argument does NOT read stdin — it
+                # opens /dev/tty and prompts, so piping the secret there stored an
+                # empty item and still exited 0. Batch mode (`security -i`) takes the
+                # whole command on stdin, which keeps the secret out of every argv
+                # (i.e. out of `ps`), and -X hex-encodes it past the tokenizer's
+                # quoting and newline rules. -U updates in place rather than stacking
+                # duplicate items.
+                command = 'add-generic-password -U -s "{}" -a "{}" -X {}\n'.format(
+                    _batch_quote(self.service), _batch_quote(key), value.encode("utf-8").hex())
+                code, _ = _run(["security", "-i"], stdin=command)
+            elif active == "libsecret":
+                code, _ = _run(["secret-tool", "store", "--label", f"{self.service} {key}",
+                                "service", self.service, "account", key], stdin=value)
+            else:  # dpapi
+                path = self._dpapi_path(key)
+                code, encrypted = _run([
+                    "powershell.exe", "-NoProfile", "-NonInteractive", "-Command",
+                    ("$in = [Console]::In.ReadToEnd().Trim(); "
+                     "ConvertTo-SecureString $in -AsPlainText -Force | ConvertFrom-SecureString"),
+                ], stdin=value)
+                if code != 0 or not encrypted.strip():
+                    return False
+                write_private(path, encrypted.strip())
+            return code == 0
+        return False
+
+    def delete(self, key: str) -> bool:
+        """Remove the stored secret for *key*. ``False`` when there was nothing to remove."""
+        active = backend()
+        if active is None:
+            return False
+        with contextlib.suppress(Exception):
+            if active == "keychain":
+                code, _ = _run(["security", "delete-generic-password", "-s", self.service, "-a", key])
+            elif active == "libsecret":
+                code, _ = _run(["secret-tool", "clear", "service", self.service, "account", key])
+            else:  # dpapi
+                path = self._dpapi_path(key)
+                path.unlink(missing_ok=True)
+                return True
+            return code == 0
+        return False
+
+
+# ── resolving, sending, entering, showing ────────────────────────────────────
+
+def resolve_credentials(token: str = "", chat_id: str = "", *,
+                        environ: Mapping[str, str] | None = None) -> tuple[str, str]:
+    """``(token, chat_id)``: what the caller configured, else the environment.
+
+    Each value falls back on its own, and blank counts as unset. Configured
+    values win so a stale ``TG_BOT_TOKEN`` in a shell profile cannot keep
+    notifying through a bot the user already replaced.
+    """
+    env = os.environ if environ is None else environ
+    return (str(token or "").strip() or env.get(TOKEN_ENV, "").strip(),
+            str(chat_id or "").strip() or env.get(CHAT_ID_ENV, "").strip())
+
+
+def send_message(token: str, chat_id: str, text: str, *, timeout: float = 10) -> bool:
+    """POST one sendMessage to the Bot API. False on missing credentials or any failure."""
+    if not token or not chat_id:
+        return False
+    data = urllib.parse.urlencode({"chat_id": chat_id, "text": text}).encode("utf-8")
+    request = urllib.request.Request(_API.format(token=token), data=data, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            response.read()
+    except (urllib.error.URLError, OSError, ValueError, http.client.HTTPException):
+        return False  # incl. InvalidURL from a hand-corrupted token
+    return True
+
+
+def notify(text: str, *, service: str, chat_id: str = "", token_key: str = TOKEN_KEY,
+           store: CredentialStore | None = None) -> bool:
+    """Send *text* with *service*'s stored token. Never raises; False on failure."""
+    store = store or CredentialStore(service)
+    token, chat = resolve_credentials(store.get(token_key), chat_id)
+    return send_message(token, chat, text)
+
+
+def read_hidden(prompt: str, *, ask: Callable[[str], str] | None = None) -> str | None:
+    """Read a secret without echo. ``None`` when echo cannot be disabled or input ends.
+
+    ``getpass`` silently falls back to an echoing prompt when it has no
+    terminal; that warning is treated as a refusal, never as consent.
+    """
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", getpass.GetPassWarning)
+            return (ask or getpass.getpass)(prompt).strip()
+    except (EOFError, OSError, getpass.GetPassWarning):
+        return None
+
+
+def mask_secret(secret: str) -> str:
+    """Stars, plus at most the last 4 characters — never enough to reuse."""
+    if not secret:
+        return ""
+    return "*" * 8 + secret[-4:] if len(secret) > 12 else "*" * 8

telegram_kit-0.1.2/tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for telegram_kit."""

telegram_kit-0.1.2/tests/test_telegram_kit.py

@@ -0,0 +1,425 @@
+"""The reusable Telegram kit other projects import. Synthetic credentials only."""
+import getpass
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+import types
+import unittest
+import urllib.parse
+import warnings
+from unittest import mock
+
+import telegram_kit
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+
+class WindowsOs:
+    """Makes ``telegram_kit.os.name`` read ``"nt"`` without touching the real
+    global ``os`` module — patching that directly breaks pathlib for every
+    other test in the process (it stops knowing which flavour it's on)."""
+    name = "nt"
+
+    def __getattr__(self, attr):
+        return getattr(os, attr)
+
+
+class Recorder:
+    def __init__(self, *results):
+        self.calls, self.results = [], list(results)
+
+    def __call__(self, argv, stdin=None):
+        self.calls.append((list(argv), stdin))
+        return self.results.pop(0) if self.results else (0, "")
+
+
+def pinned(name, run):
+    return mock.patch.multiple(telegram_kit, backend=lambda: name, _run=run)
+
+
+class StandaloneTests(unittest.TestCase):
+    def test_importing_the_kit_needs_only_the_standard_library(self):
+        """No project this kit is vendored/depended into should have to
+        install anything else just to get ``import telegram_kit``."""
+        result = subprocess.run(  # noqa: PLW1510 - want a status, not to raise
+            [sys.executable, "-I", "-c", "import telegram_kit"],
+            cwd=ROOT, env={**os.environ, "PYTHONPATH": str(ROOT / "src")},
+        )
+        self.assertEqual(result.returncode, 0)
+
+
+class CredentialStoreTests(unittest.TestCase):
+    def test_each_service_gets_its_own_keychain_namespace(self):
+        run = Recorder((0, "fake-token\n"), (0, ""))
+        store = telegram_kit.CredentialStore("other-app")
+        with pinned("keychain", run):
+            self.assertEqual(store.get("telegram_bot_token"), "fake-token")
+            self.assertTrue(store.set("telegram_bot_token", "fake-token"))
+        self.assertIn("other-app", run.calls[0][0])
+        self.assertIn('"other-app"', run.calls[1][1])
+        self.assertNotIn("fake-token", " ".join(run.calls[1][0]) + run.calls[1][1])
+
+    def test_without_a_backend_nothing_is_stored(self):
+        store = telegram_kit.CredentialStore("other-app")
+        with pinned(None, Recorder()):
+            self.assertFalse(store.set("telegram_bot_token", "fake-token"))
+            self.assertEqual(store.get("telegram_bot_token"), "")
+
+    def test_dpapi_files_live_in_the_callers_directory(self):
+        with tempfile.TemporaryDirectory() as d:
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder((0, "ciphertext\n"))):
+                self.assertTrue(store.set("telegram_bot_token", "fake-token"))
+            self.assertEqual((pathlib.Path(d) / "telegram_bot_token.dpapi").read_text(), "ciphertext")
+
+    def test_dpapi_key_cannot_escape_its_directory(self):
+        with tempfile.TemporaryDirectory() as d:
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder((0, "ciphertext\n"))):
+                self.assertFalse(store.set("../escape", "fake-token"))
+
+    def test_dpapi_get_returns_empty_when_the_file_is_missing(self):
+        with tempfile.TemporaryDirectory() as d:
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder()):
+                self.assertEqual(store.get("telegram_bot_token"), "")
+
+    def test_dpapi_get_decrypts_the_stored_file(self):
+        with tempfile.TemporaryDirectory() as d:
+            (pathlib.Path(d) / "telegram_bot_token.dpapi").write_text("ciphertext")
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder((0, "fake-token\n"))):
+                self.assertEqual(store.get("telegram_bot_token"), "fake-token")
+
+    def test_dpapi_set_fails_when_powershell_reports_an_error(self):
+        with tempfile.TemporaryDirectory() as d:
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder((1, ""))):
+                self.assertFalse(store.set("telegram_bot_token", "fake-token"))
+            self.assertFalse((pathlib.Path(d) / "telegram_bot_token.dpapi").exists())
+
+    def test_dpapi_delete_removes_the_file(self):
+        with tempfile.TemporaryDirectory() as d:
+            path = pathlib.Path(d) / "telegram_bot_token.dpapi"
+            path.write_text("ciphertext")
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder()):
+                self.assertTrue(store.delete("telegram_bot_token"))
+            self.assertFalse(path.exists())
+
+    def test_dpapi_delete_succeeds_even_when_nothing_was_stored(self):
+        with tempfile.TemporaryDirectory() as d:
+            store = telegram_kit.CredentialStore("other-app", dpapi_dir=lambda: pathlib.Path(d))
+            with pinned("dpapi", Recorder()):
+                self.assertTrue(store.delete("telegram_bot_token"))
+
+    def test_delete_without_a_backend_reports_failure(self):
+        store = telegram_kit.CredentialStore("other-app")
+        with pinned(None, Recorder()):
+            self.assertFalse(store.delete("telegram_bot_token"))
+
+
+class CredentialResolutionTests(unittest.TestCase):
+    def test_configured_values_win_over_environment(self):
+        env = {"TG_BOT_TOKEN": "env-token", "TG_CHAT_ID": "222"}
+        self.assertEqual(telegram_kit.resolve_credentials("fake-token", "111", environ=env),
+                         ("fake-token", "111"))
+
+    def test_each_value_falls_back_to_environment_on_its_own(self):
+        env = {"TG_BOT_TOKEN": " env-token ", "TG_CHAT_ID": "222"}
+        self.assertEqual(telegram_kit.resolve_credentials("", "111", environ=env), ("env-token", "111"))
+        self.assertEqual(telegram_kit.resolve_credentials("fake-token", " ", environ=env),
+                         ("fake-token", "222"))
+
+
+class SendMessageTests(unittest.TestCase):
+    def test_false_on_missing_credentials_without_a_network_call(self):
+        with mock.patch("urllib.request.urlopen") as urlopen:
+            self.assertFalse(telegram_kit.send_message("", "111", "hello"))
+            self.assertFalse(telegram_kit.send_message("fake-token", "", "hello"))
+        urlopen.assert_not_called()
+
+    def test_false_on_a_network_error_never_raises(self):
+        import urllib.error
+        with mock.patch("urllib.request.urlopen", side_effect=urllib.error.URLError("offline")):
+            self.assertFalse(telegram_kit.send_message("fake-token", "111", "hello"))
+
+    def test_false_on_a_malformed_token_never_raises(self):
+        """A hand-corrupted token can make the URL itself invalid (``InvalidURL``,
+        a ``ValueError`` subclass) — still reported as a failed send, not a crash."""
+        with mock.patch("urllib.request.urlopen", side_effect=ValueError("bad url")):
+            self.assertFalse(telegram_kit.send_message("not a token", "111", "hello"))
+
+
+class NotifyTests(unittest.TestCase):
+    def test_notify_sends_with_the_services_stored_token(self):
+        sent = []
+
+        class Response:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc):
+                return False
+
+            def read(self):
+                return b"{}"
+
+        def urlopen(request, timeout):
+            sent.append(request)
+            return Response()
+
+        with pinned("keychain", Recorder((0, "fake-token\n"))), \
+                mock.patch("urllib.request.urlopen", side_effect=urlopen), \
+                mock.patch.dict(os.environ, {}, clear=True):
+            self.assertTrue(telegram_kit.notify("hello", service="other-app", chat_id="111"))
+        self.assertIn("/botfake-token/sendMessage", sent[0].full_url)
+        self.assertEqual(urllib.parse.parse_qs(sent[0].data.decode())["chat_id"], ["111"])
+
+    def test_notify_without_credentials_reports_failure(self):
+        with pinned(None, Recorder()), mock.patch.dict(os.environ, {}, clear=True), \
+                mock.patch("urllib.request.urlopen") as urlopen:
+            self.assertFalse(telegram_kit.notify("hello", service="other-app", chat_id="111"))
+        urlopen.assert_not_called()
+
+
+class InputAndDisplayTests(unittest.TestCase):
+    def test_hidden_input_refuses_when_echo_cannot_be_disabled(self):
+        def echoing(prompt):
+            warnings.warn("echo on", getpass.GetPassWarning)
+            return "fake-token"
+        with warnings.catch_warnings(record=True):
+            self.assertIsNone(telegram_kit.read_hidden("Token: ", ask=echoing))
+
+    def test_hidden_input_returns_the_entered_secret(self):
+        self.assertEqual(telegram_kit.read_hidden("Token: ", ask=lambda _: " fake-token "), "fake-token")
+
+    def test_mask_never_shows_more_than_four_characters(self):
+        self.assertEqual(telegram_kit.mask_secret("123456:ABCDEFGHIJ"), "********GHIJ")
+        self.assertEqual(telegram_kit.mask_secret("short"), "********")
+        self.assertEqual(telegram_kit.mask_secret(""), "")
+
+
+class WritePrivateTests(unittest.TestCase):
+    def test_writes_owner_only_and_atomically(self):
+        with tempfile.TemporaryDirectory() as d:
+            target = pathlib.Path(d) / "secret.txt"
+            telegram_kit.write_private(target, "content")
+            self.assertEqual(target.read_text(), "content")
+            if os.name != "nt":
+                self.assertEqual(target.stat().st_mode & 0o777, 0o600)
+            self.assertEqual(list(pathlib.Path(d).iterdir()), [target])  # no leftover temp file
+
+    def test_refuses_to_overwrite_a_symlink(self):
+        with tempfile.TemporaryDirectory() as d:
+            real = pathlib.Path(d) / "real.txt"
+            real.write_text("untouched")
+            link = pathlib.Path(d) / "link.txt"
+            link.symlink_to(real)
+            with self.assertRaises(OSError):
+                telegram_kit.write_private(link, "attacker-controlled")
+            self.assertEqual(real.read_text(), "untouched")
+
+    def test_windows_path_runs_powershell_and_cleans_up_on_failure(self):
+        def failing_powershell(argv, input, **kwargs):
+            pathlib.Path(__import__("json").loads(input)["path"]).write_text("partial")
+            return subprocess.CompletedProcess(argv, 1)
+        with tempfile.TemporaryDirectory() as d:
+            target = pathlib.Path(d) / "secret.txt"
+            with mock.patch.object(telegram_kit, "os", WindowsOs()), \
+                    mock.patch.object(telegram_kit.subprocess, "run", side_effect=failing_powershell), \
+                    self.assertRaises(OSError):
+                telegram_kit.write_private(target, "content")
+            self.assertEqual(list(pathlib.Path(d).iterdir()), [])
+
+    def test_windows_timeout_is_oserror_and_leaves_no_temp_file(self):
+        def slow_powershell(argv, **kwargs):
+            raise subprocess.TimeoutExpired(argv, 15)
+        with tempfile.TemporaryDirectory() as d:
+            target = pathlib.Path(d) / "secret.txt"
+            with mock.patch.object(telegram_kit, "os", WindowsOs()), \
+                    mock.patch.object(telegram_kit.subprocess, "run", side_effect=slow_powershell), \
+                    self.assertRaises(OSError):
+                telegram_kit.write_private(target, "content")
+            self.assertEqual(list(pathlib.Path(d).iterdir()), [])
+
+
+class SubprocessHelperTests(unittest.TestCase):
+    def test_run_executes_and_captures_stdout(self):
+        code, out = telegram_kit._run([sys.executable, "-c", "print('hi')"])
+        self.assertEqual((code, out.strip()), (0, "hi"))
+
+    def test_unhex_decodes_a_hex_encoded_secret(self):
+        self.assertEqual(telegram_kit._unhex(b"hello".hex()), "hello")
+
+    def test_unhex_leaves_a_non_hex_secret_alone(self):
+        self.assertEqual(telegram_kit._unhex("123456:ABCDEF"), "123456:ABCDEF")
+
+    def test_unhex_leaves_hex_that_is_not_valid_utf8_alone(self):
+        garbage = bytes([0xFF, 0xFE]).hex()
+        self.assertEqual(telegram_kit._unhex(garbage), garbage)
+
+    def test_batch_quote_escapes_backslashes_and_quotes(self):
+        self.assertEqual(telegram_kit._batch_quote(r'back\slash "quote"'),
+                          r'back\\slash \"quote\"')
+
+    def test_batch_quote_rejects_a_newline(self):
+        with self.assertRaises(ValueError):
+            telegram_kit._batch_quote("line1\nline2")
+
+    def test_detect_backend_prefers_keychain_on_macos(self):
+        with mock.patch.object(telegram_kit, "IS_MACOS", True), \
+                mock.patch.object(telegram_kit, "IS_WINDOWS", False), \
+                mock.patch.object(telegram_kit.shutil, "which", return_value="/usr/bin/security"):
+            self.assertEqual(telegram_kit._detect_backend(), "keychain")
+
+    def test_detect_backend_prefers_dpapi_on_windows(self):
+        with mock.patch.object(telegram_kit, "IS_MACOS", False), \
+                mock.patch.object(telegram_kit, "IS_WINDOWS", True), \
+                mock.patch.object(telegram_kit.shutil, "which", return_value="powershell.exe"):
+            self.assertEqual(telegram_kit._detect_backend(), "dpapi")
+
+    def test_detect_backend_falls_back_to_libsecret_on_linux(self):
+        with mock.patch.object(telegram_kit, "IS_MACOS", False), \
+                mock.patch.object(telegram_kit, "IS_WINDOWS", False), \
+                mock.patch.object(telegram_kit.shutil, "which", return_value="/usr/bin/secret-tool"):
+            self.assertEqual(telegram_kit._detect_backend(), "libsecret")
+
+    def test_detect_backend_is_none_with_nothing_installed(self):
+        with mock.patch.object(telegram_kit, "IS_MACOS", False), \
+                mock.patch.object(telegram_kit, "IS_WINDOWS", False), \
+                mock.patch.object(telegram_kit.shutil, "which", return_value=None):
+            self.assertIsNone(telegram_kit._detect_backend())
+
+
+class BackendLabelTests(unittest.TestCase):
+    def test_available_and_label_reflect_the_detected_backend(self):
+        with mock.patch.object(telegram_kit, "backend", lambda: "libsecret"):
+            self.assertTrue(telegram_kit.available())
+            self.assertEqual(telegram_kit.backend_label(), "Secret Service (libsecret)")
+
+    def test_unavailable_when_nothing_is_detected(self):
+        with mock.patch.object(telegram_kit, "backend", lambda: None):
+            self.assertFalse(telegram_kit.available())
+            self.assertEqual(telegram_kit.backend_label(), "none")
+
+    def test_backend_probes_only_once_and_caches_the_result(self):
+        telegram_kit.backend.cache_clear()
+        try:
+            with mock.patch.object(telegram_kit, "_detect_backend", return_value="keychain") as probe:
+                self.assertEqual(telegram_kit.backend(), "keychain")
+                self.assertEqual(telegram_kit.backend(), "keychain")
+            probe.assert_called_once()
+        finally:
+            telegram_kit.backend.cache_clear()
+
+
+class DpapiDirTests(unittest.TestCase):
+    def test_defaults_to_appdata_when_set(self):
+        with mock.patch.dict(os.environ, {"APPDATA": r"C:\Users\wes\AppData\Roaming"}):
+            self.assertEqual(telegram_kit._default_dpapi_dir("other-app"),
+                              pathlib.Path(r"C:\Users\wes\AppData\Roaming") / "other-app")
+
+    def test_falls_back_to_home_when_appdata_is_unset(self):
+        with mock.patch.dict(os.environ):
+            os.environ.pop("APPDATA", None)
+            self.assertEqual(telegram_kit._default_dpapi_dir("other-app"),
+                              pathlib.Path.home() / "AppData" / "Roaming" / "other-app")
+
+
+def _fake_winreg(*, value=None, opening_fails=False):
+    module = types.SimpleNamespace(HKEY_CURRENT_USER=object())
+
+    class _Key:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+    def open_key(hive, path):
+        if opening_fails:
+            raise OSError("no such registry key")
+        return _Key()
+
+    module.OpenKey = open_key
+    module.QueryValueEx = lambda key, name: (value, 1)
+    return module
+
+
+class LegacyWindowsTokenTests(unittest.TestCase):
+    def test_false_on_non_windows_without_touching_the_registry(self):
+        with mock.patch.object(telegram_kit, "IS_WINDOWS", False):
+            self.assertFalse(telegram_kit.legacy_windows_env_token_present())
+
+    def test_true_when_the_registry_still_holds_a_token(self):
+        with mock.patch.object(telegram_kit, "IS_WINDOWS", True), \
+                mock.patch.dict(sys.modules, {"winreg": _fake_winreg(value="fake-token")}):
+            self.assertTrue(telegram_kit.legacy_windows_env_token_present())
+
+    def test_false_when_the_stored_value_is_empty(self):
+        with mock.patch.object(telegram_kit, "IS_WINDOWS", True), \
+                mock.patch.dict(sys.modules, {"winreg": _fake_winreg(value="")}):
+            self.assertFalse(telegram_kit.legacy_windows_env_token_present())
+
+    def test_false_when_the_registry_key_does_not_exist(self):
+        with mock.patch.object(telegram_kit, "IS_WINDOWS", True), \
+                mock.patch.dict(sys.modules, {"winreg": _fake_winreg(opening_fails=True)}):
+            self.assertFalse(telegram_kit.legacy_windows_env_token_present())
+
+
+class CredentialStoreLibsecretAndKeychainTests(unittest.TestCase):
+    """The keychain/libsecret argv shapes get/set/delete build, and that a
+    non-zero exit or a raised exception both mean "no secret" rather than a
+    crash — mirrors CredentialStoreTests but for the two backends that test
+    class's dpapi-focused cases don't touch."""
+
+    def test_libsecret_get_set_delete_argv(self):
+        store = telegram_kit.CredentialStore("other-app")
+        run = Recorder((0, "fake-token\n"), (0, ""), (0, ""))
+        with pinned("libsecret", run):
+            self.assertEqual(store.get("telegram_bot_token"), "fake-token")
+            self.assertTrue(store.set("telegram_bot_token", "fake-token"))
+            self.assertTrue(store.delete("telegram_bot_token"))
+        get_argv, set_argv, delete_argv = (c[0] for c in run.calls)
+        self.assertEqual(get_argv, ["secret-tool", "lookup", "service", "other-app",
+                                     "account", "telegram_bot_token"])
+        self.assertEqual(set_argv[:2], ["secret-tool", "store"])
+        self.assertEqual(run.calls[1][1], "fake-token")  # secret travels on stdin, not argv
+        self.assertEqual(delete_argv, ["secret-tool", "clear", "service", "other-app",
+                                        "account", "telegram_bot_token"])
+
+    def test_keychain_delete_argv(self):
+        store = telegram_kit.CredentialStore("other-app")
+        run = Recorder((0, ""))
+        with pinned("keychain", run):
+            self.assertTrue(store.delete("telegram_bot_token"))
+        self.assertEqual(run.calls[0][0], ["security", "delete-generic-password",
+                                            "-s", "other-app", "-a", "telegram_bot_token"])
+
+    def test_a_nonzero_exit_reads_as_no_secret_not_a_crash(self):
+        store = telegram_kit.CredentialStore("other-app")
+        with pinned("keychain", Recorder((1, ""))):
+            self.assertEqual(store.get("telegram_bot_token"), "")
+
+    def test_a_raising_helper_reads_as_no_secret_not_a_crash(self):
+        def exploding(argv, stdin=None):
+            raise OSError("helper vanished")
+        store = telegram_kit.CredentialStore("other-app")
+        with pinned("keychain", exploding):
+            self.assertEqual(store.get("telegram_bot_token"), "")
+            self.assertFalse(store.set("telegram_bot_token", "fake-token"))
+            self.assertFalse(store.delete("telegram_bot_token"))
+
+    def test_setting_an_empty_value_deletes_instead_of_storing_blank(self):
+        store = telegram_kit.CredentialStore("other-app")
+        run = Recorder((0, ""))
+        with pinned("keychain", run):
+            self.assertTrue(store.set("telegram_bot_token", ""))
+        self.assertEqual(run.calls[0][0][:2], ["security", "delete-generic-password"])
+
+
+if __name__ == "__main__":
+    unittest.main()

telegram_kit-0.1.2/uv.lock

@@ -0,0 +1,43 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "ruff"
+version = "0.16.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/96/bf/c935ca98e73fe8ce65b87ef08a280c0c1e85295d569228c15e87d8fdfaf1/ruff-0.16.9.tar.gz", hash = "sha256:12b625c6cfba78d285d9f48eda5f053374f1e53cb10ef17342a383750db99161", size = 4948764, upload-time = "2026-09-24T20:37:49.416Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0d/26/df51322b52ee1ada7eff2d071ea09d11d5c2d1dcc9f02594f5785c4d1635/ruff-0.16.9-py3-none-linux_armv6l.whl", hash = "sha256:95e6f022090368ab3b824c36276839c53b2adf1a3f4c09fefc33dfc400f6da96", size = 10082922, upload-time = "2026-09-24T20:37:13.045Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/27/7bf51f5a7aa375e9f339280a303aab44ca75dc1525f1cdc5991761685b0f/ruff-0.16.9-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:a5f27be168556594a86d2f415db0cf43f5291917849318f873c7e2791f7a8c67", size = 10236360, upload-time = "2026-09-24T20:37:16.049Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/63/09659283f92f02dff45809da194a70da2f688d87c55d8875c4fae3536072/ruff-0.16.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:1632eb1d6197f33bd00b1acbc5b71009e89a8895c158e2d2b03a834fac964ab6", size = 9892940, upload-time = "2026-09-24T20:37:17.957Z" },
+    { url = "https://files.pythonhosted.org/packages/24/58/98de1b72ec172f5f8f1731236fe21585b3998bf7dfe9fcc44ae9ba626012/ruff-0.16.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b3f951b14d865d5952c89d40a5ca07e87abe24fa5453299878411e127748fb1c", size = 10032114, upload-time = "2026-09-24T20:37:19.942Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/7d/f1e17c54ab59d4bad1dce8ee3e22a7a1d0ef4745240decacdcf3832b5bb2/ruff-0.16.9-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:447fc07e1573afff7cb02803462b12b6c8ece7cf10e2cd78565fa6d7a1c0bf8d", size = 9910227, upload-time = "2026-09-24T20:37:21.872Z" },
+    { url = "https://files.pythonhosted.org/packages/34/19/436f647a65075bbd3bab2668b3bdaa5120559b294694018cdcefabbbf30b/ruff-0.16.9-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8a3e039a6a40ed976c491722b60e0ae4a4aa1a86057f540ee7a37a5d19ae9120", size = 10547484, upload-time = "2026-09-24T20:37:24.229Z" },
+    { url = "https://files.pythonhosted.org/packages/03/59/38430a6bc2f6d8095447ac39625cf8b6e9344a47e6c26225c8ba1bff3ffb/ruff-0.16.9-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4684dded7db60aa57cb118fa158630f5feade4af5782903b6053484bdf9bd129", size = 11412367, upload-time = "2026-09-24T20:37:26.307Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/bd/bbb6d7fc7f208c8b8c50dd5dc8206e4cfdb1e7a8fb852606a3adf370c880/ruff-0.16.9-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d29c934357e45642fda2f34c0b1f4025b4a6c01e15e4bf0016879d60078a142c", size = 10869787, upload-time = "2026-09-24T20:37:28.35Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/b8/9c543074918061abbefc3bd139bee22de35abedb00dde0f2d27288838962/ruff-0.16.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a21713e629d3e5bdb2f5c2def1cc7f04f47fa8e1a7eb0571b4a28e1da64bc728", size = 10406494, upload-time = "2026-09-24T20:37:30.624Z" },
+    { url = "https://files.pythonhosted.org/packages/35/7a/5a8851bd146e7ccf8fd4b003f6c75c11f8fbdb0e60673b45097986b6bf41/ruff-0.16.9-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:7baa24ef5fc8e77aa93879e1d3f43754a01ae488e869f1ae30cf431afd4d2452", size = 10590083, upload-time = "2026-09-24T20:37:32.439Z" },
+    { url = "https://files.pythonhosted.org/packages/87/f0/4c3467188f23f806960b46fa76575a7cd0514c9ba90562650b71efc96980/ruff-0.16.9-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a41aac6230aadfaa133bdfa1614488531ffa3e0837567ae04c0da2058a9c0f9e", size = 10119151, upload-time = "2026-09-24T20:37:34.581Z" },
+    { url = "https://files.pythonhosted.org/packages/15/34/5a4def5adea572ce6aea0bb64f21f928ee317b80e0db747d7979b01d7261/ruff-0.16.9-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:c2529fb5896d49115b0e9aa8f887490b34bbe76baf879ec2264ac59406869ce7", size = 9911544, upload-time = "2026-09-24T20:37:36.796Z" },
+    { url = "https://files.pythonhosted.org/packages/62/5d/d15ebea7499eef9373318c0ee6ca127832927c6529731f6d48e18dce7ca9/ruff-0.16.9-py3-none-musllinux_1_2_i686.whl", hash = "sha256:41e3870277694177429b56406d65dfbdb2c2802c52b715edaf6a0b829c69d4ee", size = 10269884, upload-time = "2026-09-24T20:37:38.857Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/56/c5d3cd119ded7a3c7aba0e961b69cb3df701c91662c98ad694467d060ce1/ruff-0.16.9-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:8adbe4e58af167f767d7b2ba5e83c42e878350796cf78c2f5e14ab9903a92588", size = 10749366, upload-time = "2026-09-24T20:37:41.042Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/fe/734ec7527029ac757ecf821f143c9f3fcf69149c21f53a044a899b430f5a/ruff-0.16.9-py3-none-win32.whl", hash = "sha256:0e1dbc2073624dee6618d41d0098690a7244654af746704b64759e12b6b6b385", size = 10152355, upload-time = "2026-09-24T20:37:43.025Z" },
+    { url = "https://files.pythonhosted.org/packages/14/21/26e4643629b3ebb44f0a06f9c9a53058d63d989415f63a9a3c28e2ee7f22/ruff-0.16.9-py3-none-win_amd64.whl", hash = "sha256:6bd40fec8cd4c8a3d4dd589bd8ad4e6320c13c29234159bfd959a40d529d597b", size = 10592965, upload-time = "2026-09-24T20:37:44.944Z" },
+    { url = "https://files.pythonhosted.org/packages/51/60/5fb1a39dbb5ae314d5f59bc7348a63c1d5c20f3cd83914c4b5cb0be31d2d/ruff-0.16.9-py3-none-win_arm64.whl", hash = "sha256:ed1a252039200f57a59eebc063b54beabea67bfbaaca0eeaa7f54b5fbcda2284", size = 10458649, upload-time = "2026-09-24T20:37:46.882Z" },
+]
+
+[[package]]
+name = "telegram-kit"
+version = "0.1.2"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "ruff" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [{ name = "ruff", specifier = ">=0.15.21" }]