loosekeys 0.1.0__tar.gz

loosekeys-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.loosekeys.bak

loosekeys-0.1.0/LICENSE

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

loosekeys-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: loosekeys
+Version: 0.1.0
+Summary: Find API keys and tokens sitting in plain text on your machine: shell history, .env files, AI tool configs. Masked output, nothing leaves your computer.
+Project-URL: Homepage, https://github.com/ArkaKhorchidian/loosekeys
+Project-URL: Issues, https://github.com/ArkaKhorchidian/loosekeys/issues
+Author: Arka Khorchidian
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-keys,cli,credentials,devsecops,dotenv,mcp,secret-scanning,secrets,security,shell-history
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: rich>=13
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+<h1 align="center">loosekeys</h1>
+
+<p align="center"><b>Find the API keys sitting in plain text on your laptop.</b><br>
+Shell history, forgotten <code>.env</code> files, AI tool and MCP configs, CLI credential stores. One command, nothing leaves your machine.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/loosekeys/"><img src="https://img.shields.io/pypi/v/loosekeys.svg" alt="PyPI"></a>
+  <a href="https://github.com/ArkaKhorchidian/loosekeys/actions/workflows/ci.yml"><img src="https://github.com/ArkaKhorchidian/loosekeys/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/loosekeys.svg" alt="Python">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
+</p>
+
+```bash
+uvx loosekeys        # or: pipx run loosekeys
+```
+
+<p align="center">
+  <img src="docs/demo.gif" alt="loosekeys scanning a home directory and finding API keys in shell history, .env files and MCP configs" width="760">
+  <br><sub>Demo run against a sandboxed home directory filled with fake keys.</sub>
+</p>
+
+Repo scanners like gitleaks and trufflehog guard what you *commit*. But most leaked keys never
+get near a commit. They're the `export OPENAI_API_KEY=sk-...` you typed into your terminal
+eight months ago and your shell has saved ever since; the `.env` in a side project you forgot
+existed; the GitHub token you pasted into an MCP server config. loosekeys looks where those
+end up.
+
+## What it checks
+
+| Where | Why it matters |
+|---|---|
+| **Shell & REPL history** (zsh, bash, fish, PowerShell, Python, Node, psql, MySQL, ...) | Every key you ever typed or pasted, saved in plain text, forever |
+| **Shell config** (`.zshrc`, `.bashrc`, `.profile`, fish, PowerShell profile) | Exported keys are readable by every program you run, including every npm `postinstall` script |
+| **AI tools & MCP servers** (Claude Code & Desktop, Cursor, Windsurf, VS Code, Continue, aider, Gemini CLI, Codex, Zed, llm) | Keys pasted into JSON config files |
+| **Project files** (`.env*`, `secrets.toml`, `*.tfvars`, service-account JSON, docker-compose, ...) across your home folder | Flags files **committed to git** and projects you haven't touched in 6+ months |
+| **CLI credential stores** (`~/.aws`, `.npmrc`, `.pypirc`, `.netrc`, Docker, kubectl, gcloud, gh, Cargo, ...) | Where tools expect logins to live, but still plain text |
+| **SSH keys** | Private keys with no passphrase |
+
+It recognizes 30+ token formats precisely: OpenAI, Anthropic, GitHub, GitLab, AWS, Google, Stripe,
+Slack, Hugging Face, npm, PyPI, Groq, xAI, OpenRouter, Supabase, DigitalOcean, Twilio, SendGrid,
+Telegram, database URLs with passwords, private keys, and more. It also catches `SOMETHING_API_KEY=...`
+style assignments while ignoring placeholders like `your_key_here`, `${VAR}` and `changeme`.
+
+## Clean up
+
+```bash
+loosekeys --redact-history
+```
+
+This replaces every secret in your history files with `[REDACTED]`:
+- every other byte stays untouched, including zsh's history encoding
+- it keeps a backup first (`.zsh_history.loosekeys.bak`, owner-only permissions)
+- it writes atomically
+
+Close other terminal sessions first: open shells hold their history in memory and can write it back.
+
+Redacting doesn't make a leaked key safe. The report links to each provider's page for **rotating**
+the keys that ended up in history, shell config or git, and tells you what to do about the rest.
+
+## Privacy
+
+- **Nothing leaves your machine.** loosekeys makes no network requests, ever.
+- **Secrets are never printed.** Values show as `sk-proj••••••Gi`, in the terminal and in `--json`
+  alike. The test suite asserts no full secret appears in any output.
+- **It's read-only** unless you pass `--redact-history`.
+
+## Options
+
+```bash
+loosekeys ~/code ~/work      # search these folders for project files instead of your whole home
+loosekeys --no-projects      # only check the well-known locations (fast)
+loosekeys --json             # machine-readable, still masked; exit code 1 if anything is found
+```
+
+## Install
+
+```bash
+pipx install loosekeys       # or: uv tool install loosekeys / pip install loosekeys
+```
+
+Python 3.9+ on macOS, Linux and Windows. Zero config. The only dependency is
+[rich](https://github.com/Textualize/rich).
+
+## Contributing
+
+New token formats and new tool config locations are the most useful contributions. Add the
+pattern in `detectors.py`, add a fake example in `tests/fakehome.py` (built at runtime, never
+committed as a literal), and run `pytest`.
+
+## License
+
+MIT

loosekeys-0.1.0/README.md

@@ -0,0 +1,92 @@
+<h1 align="center">loosekeys</h1>
+
+<p align="center"><b>Find the API keys sitting in plain text on your laptop.</b><br>
+Shell history, forgotten <code>.env</code> files, AI tool and MCP configs, CLI credential stores. One command, nothing leaves your machine.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/loosekeys/"><img src="https://img.shields.io/pypi/v/loosekeys.svg" alt="PyPI"></a>
+  <a href="https://github.com/ArkaKhorchidian/loosekeys/actions/workflows/ci.yml"><img src="https://github.com/ArkaKhorchidian/loosekeys/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/loosekeys.svg" alt="Python">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
+</p>
+
+```bash
+uvx loosekeys        # or: pipx run loosekeys
+```
+
+<p align="center">
+  <img src="docs/demo.gif" alt="loosekeys scanning a home directory and finding API keys in shell history, .env files and MCP configs" width="760">
+  <br><sub>Demo run against a sandboxed home directory filled with fake keys.</sub>
+</p>
+
+Repo scanners like gitleaks and trufflehog guard what you *commit*. But most leaked keys never
+get near a commit. They're the `export OPENAI_API_KEY=sk-...` you typed into your terminal
+eight months ago and your shell has saved ever since; the `.env` in a side project you forgot
+existed; the GitHub token you pasted into an MCP server config. loosekeys looks where those
+end up.
+
+## What it checks
+
+| Where | Why it matters |
+|---|---|
+| **Shell & REPL history** (zsh, bash, fish, PowerShell, Python, Node, psql, MySQL, ...) | Every key you ever typed or pasted, saved in plain text, forever |
+| **Shell config** (`.zshrc`, `.bashrc`, `.profile`, fish, PowerShell profile) | Exported keys are readable by every program you run, including every npm `postinstall` script |
+| **AI tools & MCP servers** (Claude Code & Desktop, Cursor, Windsurf, VS Code, Continue, aider, Gemini CLI, Codex, Zed, llm) | Keys pasted into JSON config files |
+| **Project files** (`.env*`, `secrets.toml`, `*.tfvars`, service-account JSON, docker-compose, ...) across your home folder | Flags files **committed to git** and projects you haven't touched in 6+ months |
+| **CLI credential stores** (`~/.aws`, `.npmrc`, `.pypirc`, `.netrc`, Docker, kubectl, gcloud, gh, Cargo, ...) | Where tools expect logins to live, but still plain text |
+| **SSH keys** | Private keys with no passphrase |
+
+It recognizes 30+ token formats precisely: OpenAI, Anthropic, GitHub, GitLab, AWS, Google, Stripe,
+Slack, Hugging Face, npm, PyPI, Groq, xAI, OpenRouter, Supabase, DigitalOcean, Twilio, SendGrid,
+Telegram, database URLs with passwords, private keys, and more. It also catches `SOMETHING_API_KEY=...`
+style assignments while ignoring placeholders like `your_key_here`, `${VAR}` and `changeme`.
+
+## Clean up
+
+```bash
+loosekeys --redact-history
+```
+
+This replaces every secret in your history files with `[REDACTED]`:
+- every other byte stays untouched, including zsh's history encoding
+- it keeps a backup first (`.zsh_history.loosekeys.bak`, owner-only permissions)
+- it writes atomically
+
+Close other terminal sessions first: open shells hold their history in memory and can write it back.
+
+Redacting doesn't make a leaked key safe. The report links to each provider's page for **rotating**
+the keys that ended up in history, shell config or git, and tells you what to do about the rest.
+
+## Privacy
+
+- **Nothing leaves your machine.** loosekeys makes no network requests, ever.
+- **Secrets are never printed.** Values show as `sk-proj••••••Gi`, in the terminal and in `--json`
+  alike. The test suite asserts no full secret appears in any output.
+- **It's read-only** unless you pass `--redact-history`.
+
+## Options
+
+```bash
+loosekeys ~/code ~/work      # search these folders for project files instead of your whole home
+loosekeys --no-projects      # only check the well-known locations (fast)
+loosekeys --json             # machine-readable, still masked; exit code 1 if anything is found
+```
+
+## Install
+
+```bash
+pipx install loosekeys       # or: uv tool install loosekeys / pip install loosekeys
+```
+
+Python 3.9+ on macOS, Linux and Windows. Zero config. The only dependency is
+[rich](https://github.com/Textualize/rich).
+
+## Contributing
+
+New token formats and new tool config locations are the most useful contributions. Add the
+pattern in `detectors.py`, add a fake example in `tests/fakehome.py` (built at runtime, never
+committed as a literal), and run `pytest`.
+
+## License
+
+MIT

loosekeys-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loosekeys"
+version = "0.1.0"
+description = "Find API keys and tokens sitting in plain text on your machine: shell history, .env files, AI tool configs. Masked output, nothing leaves your computer."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Arka Khorchidian" }]
+requires-python = ">=3.9"
+dependencies = ["rich>=13"]
+keywords = ["security", "secrets", "api-keys", "credentials", "secret-scanning", "dotenv", "shell-history", "mcp", "devsecops", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+  "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+loosekeys = "loosekeys.cli:run"
+
+[project.urls]
+Homepage = "https://github.com/ArkaKhorchidian/loosekeys"
+Issues = "https://github.com/ArkaKhorchidian/loosekeys/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loosekeys"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["docs", ".github"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]

loosekeys-0.1.0/src/loosekeys/__init__.py

@@ -0,0 +1,2 @@
+"""loosekeys: find API keys and tokens sitting in plain text on your machine."""
+__version__ = "0.1.0"

loosekeys-0.1.0/src/loosekeys/__main__.py

@@ -0,0 +1,3 @@
+from .cli import run
+
+run()

loosekeys-0.1.0/src/loosekeys/cli.py

@@ -0,0 +1,65 @@
+"""loosekeys command line."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from . import __version__
+from .fix import redact_histories
+from .locations import default_roots, fixed_locations, project_files, ssh_keys
+from .report import render, short
+from .scan import scan
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="loosekeys",
+        description="Find API keys and tokens sitting in plain text on your machine. Values are masked "
+                    "and nothing leaves your computer.")
+    p.add_argument("paths", nargs="*", type=Path, help="folders to search for project files (default: your home)")
+    p.add_argument("--redact-history", action="store_true",
+                   help="replace secrets in shell/REPL history files with [REDACTED] (backups are kept)")
+    p.add_argument("--json", action="store_true", help="machine-readable output (values stay masked)")
+    p.add_argument("--no-projects", action="store_true", help="skip the .env / project-file search")
+    p.add_argument("--depth", type=int, default=6, help="how deep to search for project files (default 6)")
+    p.add_argument("--version", action="version", version=f"loosekeys {__version__}")
+    a = p.parse_args(argv)
+
+    console = Console(stderr=a.json)
+    locations = fixed_locations() + ssh_keys()
+    if not a.no_projects:
+        with console.status("[dim]looking through your projects…[/]", spinner="dots"):
+            locations += list(project_files(a.paths or default_roots(), max_depth=a.depth))
+
+    if a.redact_history:
+        done = redact_histories(locations)
+        if not done:
+            console.print("No secrets found in your history files.")
+        for path, n, backup in done:
+            console.print(f"[bold green]✓[/] {short(path)}: redacted {n} secret{'s' if n > 1 else ''} "
+                          f"[dim](backup: {short(backup)}; delete it once you're happy)[/]")
+        if done:
+            console.print("[dim]Already-open shells keep their old history in memory: close them, or the "
+                          "secrets may be written back on exit. Redacting doesn't revoke anything: rotate the keys.[/]")
+
+    with console.status("[dim]scanning…[/]", spinner="dots"):
+        report = scan(locations)
+
+    if a.json:
+        print(json.dumps({"score": report.score, "counts": report.counts(), "scanned_files": report.scanned_files,
+                          "findings": [f.to_dict() for f in report.findings]}, indent=2))
+    else:
+        render(report, console)
+    return 1 if report.findings else 0
+
+
+def run() -> None:
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    run()

loosekeys-0.1.0/src/loosekeys/detectors.py

@@ -0,0 +1,155 @@
+"""What a secret looks like.
+
+Provider-specific patterns first (precise: a match is almost certainly real), then a
+conservative generic rule that only fires on `NAME=value` assignments whose name says
+it's a secret and whose value doesn't look like a placeholder.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Iterator
+
+CRITICAL, HIGH, MEDIUM, LOW = "critical", "high", "medium", "low"
+SEVERITY_ORDER = {CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3}
+
+
+@dataclass(frozen=True)
+class Detector:
+    id: str
+    name: str
+    severity: str
+    pattern: re.Pattern
+    group: int = 0  # capture group holding the secret itself
+    rotate: str = ""  # where to revoke/rotate it
+
+
+def _d(id, name, severity, regex, group=0, rotate="", flags=0):
+    return Detector(id, name, severity, re.compile(regex, flags), group, rotate)
+
+
+DETECTORS: list[Detector] = [
+    # --- private keys ---------------------------------------------------------
+    _d("private-key", "Private key", CRITICAL,
+       r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----"),
+    # --- AI providers -------------------------------------------------------------
+    _d("anthropic", "Anthropic API key", HIGH, r"\bsk-ant-(?:api03|admin01)-[A-Za-z0-9_\-]{32,}",
+       rotate="https://console.anthropic.com/settings/keys"),
+    _d("openrouter", "OpenRouter API key", HIGH, r"\bsk-or-v1-[a-f0-9]{64}\b",
+       rotate="https://openrouter.ai/settings/keys"),
+    _d("openai", "OpenAI API key", HIGH,
+       r"\bsk-(?:proj-|svcacct-|admin-)[A-Za-z0-9_\-]{40,}|\bsk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}\b",
+       rotate="https://platform.openai.com/api-keys"),
+    _d("groq", "Groq API key", HIGH, r"\bgsk_[A-Za-z0-9]{52}\b", rotate="https://console.groq.com/keys"),
+    _d("xai", "xAI API key", HIGH, r"\bxai-[A-Za-z0-9]{70,90}\b", rotate="https://console.x.ai"),
+    _d("perplexity", "Perplexity API key", HIGH, r"\bpplx-[A-Za-z0-9]{48}\b"),
+    _d("huggingface", "Hugging Face token", HIGH, r"\bhf_[A-Za-z0-9]{34,40}\b",
+       rotate="https://huggingface.co/settings/tokens"),
+    _d("replicate", "Replicate API token", HIGH, r"\br8_[A-Za-z0-9]{37}\b"),
+    # --- code hosting & package registries ----------------------------------------
+    _d("github", "GitHub token", CRITICAL, r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b|\bgithub_pat_[A-Za-z0-9_]{82}\b",
+       rotate="https://github.com/settings/tokens"),
+    _d("gitlab", "GitLab token", CRITICAL, r"\bglpat-[A-Za-z0-9_\-]{20,}\b"),
+    _d("npm", "npm token", CRITICAL, r"\bnpm_[A-Za-z0-9]{36}\b", rotate="https://www.npmjs.com/settings/~/tokens"),
+    _d("pypi", "PyPI token", CRITICAL, r"\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_\-]{50,}",
+       rotate="https://pypi.org/manage/account/token/"),
+    # --- cloud ----------------------------------------------------------------------
+    _d("aws-key-id", "AWS access key ID", HIGH, r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b",
+       rotate="https://console.aws.amazon.com/iam/home#/security_credentials"),
+    _d("aws-secret", "AWS secret access key", CRITICAL,
+       r"(?i)aws_?secret_?access_?key[\"']?\s*[=:]\s*[\"']?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])", group=1,
+       rotate="https://console.aws.amazon.com/iam/home#/security_credentials"),
+    _d("google-api", "Google API key", HIGH, r"\bAIza[0-9A-Za-z_\-]{35}(?![0-9A-Za-z_\-])",
+       rotate="https://console.cloud.google.com/apis/credentials"),
+    _d("google-refresh", "Google OAuth refresh token", HIGH, r"\b1//0[A-Za-z0-9_\-]{30,}"),
+    _d("digitalocean", "DigitalOcean token", CRITICAL, r"\bdo[po]_v1_[a-f0-9]{64}\b"),
+    _d("supabase", "Supabase secret", CRITICAL, r"\bsbp_[a-f0-9]{40}\b|\bsb_secret_[A-Za-z0-9_\-]{20,}"),
+    # --- payments & messaging -------------------------------------------------------
+    _d("stripe-live", "Stripe live secret key", CRITICAL, r"\b[sr]k_live_[A-Za-z0-9]{24,}\b",
+       rotate="https://dashboard.stripe.com/apikeys"),
+    _d("stripe-test", "Stripe test key", LOW, r"\b[sr]k_test_[A-Za-z0-9]{24,}\b"),
+    _d("slack-token", "Slack token", HIGH, r"\bxox[baprs]-[A-Za-z0-9-]{10,}"),
+    _d("slack-webhook", "Slack webhook", MEDIUM, r"https://hooks\.slack\.com/services/T[A-Z0-9]+/B[A-Z0-9]+/[A-Za-z0-9]{20,}"),
+    _d("discord-webhook", "Discord webhook", MEDIUM,
+       r"https://(?:ptb\.|canary\.)?discord(?:app)?\.com/api/webhooks/\d+/[A-Za-z0-9_\-]{40,}"),
+    _d("telegram", "Telegram bot token", HIGH, r"\b\d{8,10}:AA[A-Za-z0-9_\-]{33}\b"),
+    _d("sendgrid", "SendGrid API key", HIGH, r"\bSG\.[A-Za-z0-9_\-]{22}\.[A-Za-z0-9_\-]{43}\b"),
+    _d("twilio", "Twilio API key", HIGH, r"\bSK[0-9a-f]{32}\b"),
+    _d("mailgun", "Mailgun API key", HIGH, r"\bkey-[a-f0-9]{32}\b"),
+    _d("linear", "Linear API key", MEDIUM, r"\blin_api_[A-Za-z0-9]{40}\b"),
+    _d("notion", "Notion token", MEDIUM, r"\b(?:secret_|ntn_)[A-Za-z0-9]{43,}\b"),
+    _d("shopify", "Shopify token", HIGH, r"\bshp(?:at|ca|pa|ss)_[a-fA-F0-9]{32}\b"),
+    # --- connection strings -----------------------------------------------------------
+    _d("db-url", "Database URL with password", HIGH,
+       r"\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|rediss?|amqps?)://[^:\s/@'\"]+:([^@\s/'\"]{4,})@[^\s'\"]+",
+       group=1),
+]
+
+GENERIC = _d(
+    "generic", "Secret assignment", MEDIUM,
+    r"(?i)(?:^|[\s;'\"{,]|export\s+)((?:[A-Z][A-Z0-9_]*)?(?:API_?KEY|SECRET(?:_?KEY)?|_TOKEN|AUTH_?TOKEN|ACCESS_?KEY|PASSWORD|PASSWD|PRIVATE_?KEY))"
+    r"[\"']?\s*[=:]\s*[\"']?([^\s\"'#,}()\[\];]{12,})(?![(\[.])", group=2)
+
+_PLACEHOLDER = re.compile(
+    r"^(?:x{4,}|\*{3,}|\.{3,}|<.*>|\{\{.*\}\}|\$.*|%.*%|your[_-].*|.*example.*|.*placeholder.*|change[_-]?me.*|"
+    r"dummy.*|fake.*|test.*|sample.*|todo|none|null|true|false|redacted.*|\[redacted\].*|secret|password)$", re.I)
+
+
+def entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    counts = {c: s.count(c) for c in set(s)}
+    return -sum(n / len(s) * math.log2(n / len(s)) for n in counts.values())
+
+
+def looks_like_placeholder(value: str) -> bool:
+    v = value.strip().strip("\"'")
+    if _PLACEHOLDER.match(v) or v.startswith(("/", "~", "./", "http://localhost", "file:")):
+        return True
+    if len(set(v)) <= 3 or entropy(v) < 3.0:
+        return True
+    has_alpha, has_digit = any(c.isalpha() for c in v), any(c.isdigit() for c in v)
+    return not (has_alpha and has_digit)
+
+
+def mask(secret: str) -> str:
+    """Show just enough to recognise a key, never enough to use it."""
+    if len(secret) <= 8:
+        return "•" * 6
+    head = 7 if secret.startswith(("sk-", "ghp_", "gho_", "hf_", "npm_", "AKIA", "AIza", "xox", "glpat")) else 4
+    head = min(head, len(secret) // 3)
+    return secret[:head] + "•" * 6 + secret[-2:]
+
+
+@dataclass(frozen=True)
+class Match:
+    detector: Detector
+    secret: str
+    start: int
+    end: int
+
+
+def find(text: str, generic: bool = True) -> Iterator[Match]:
+    """All non-overlapping secrets in `text`, specific detectors taking precedence."""
+    taken: list[tuple[int, int]] = []
+
+    def free(a, b):
+        return all(b <= s or a >= e for s, e in taken)
+
+    for det in DETECTORS:
+        for m in det.pattern.finditer(text):
+            a, b = m.span(det.group)
+            secret = m.group(det.group)
+            if det.id == "db-url" and looks_like_placeholder(secret):
+                continue
+            if free(a, b):
+                taken.append((a, b))
+                yield Match(det, secret, a, b)
+    if generic:
+        for m in GENERIC.pattern.finditer(text):
+            a, b = m.span(2)
+            secret = m.group(2)
+            if free(a, b) and not looks_like_placeholder(secret):
+                taken.append((a, b))
+                yield Match(GENERIC, secret, a, b)

loosekeys-0.1.0/src/loosekeys/fix.py

@@ -0,0 +1,56 @@
+"""Redact secrets from history files, with a backup first."""
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import tempfile
+from pathlib import Path
+
+from . import detectors as D
+from .locations import HISTORY, Location
+
+REDACTED = "[REDACTED]"
+
+
+def redact_text(text: str) -> tuple[str, int]:
+    """Replace every secret in `text`; returns (new_text, number_replaced)."""
+    matches = sorted(D.find(text), key=lambda m: m.start, reverse=True)
+    for m in matches:
+        text = text[:m.start] + REDACTED + text[m.end:]
+    return text, len(matches)
+
+
+def redact_file(path: Path) -> tuple[int, Path | None]:
+    """Redact in place. Writes `<file>.loosekeys.bak` (owner-only) first. Returns (count, backup)."""
+    raw = path.read_bytes()
+    text = raw.decode("latin-1")  # byte-exact round trip (zsh "metafies" non-ASCII bytes)
+    new, n = redact_text(text)
+    if n == 0:
+        return 0, None
+    backup = path.with_name(path.name + ".loosekeys.bak")
+    shutil.copy2(path, backup)
+    os.chmod(backup, stat.S_IRUSR | stat.S_IWUSR)
+    mode = stat.S_IMODE(path.stat().st_mode)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(new.encode("latin-1"))
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)  # atomic: the history file is never half-written
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    return n, backup
+
+
+def redact_histories(locations: list[Location]) -> list[tuple[Path, int, Path]]:
+    done = []
+    for loc in locations:
+        if loc.kind != HISTORY:
+            continue
+        n, backup = redact_file(loc.path)
+        if n:
+            done.append((loc.path, n, backup))
+    return done