Skip to main content

Worthless

Make leaked API keys worthless.

All modern LLM ecosystem balanced on a .env file
Based on XKCD #2347 by Randall Munroe (CC BY-NC 2.5)

Python 3.10+ License: AGPL-3.0 Tests OpenSSF Scorecard Known Vulnerabilities

When your .env leaks, the keys inside are placeholders. The real key never sits in your repo, your shell history, or your laptop's memory.

Scope: this makes a leaked file worthless — git history, CI logs, a screenshot, a scraper. It does not protect a machine an attacker already controls: with code execution or filesystem access they can read the shard and proxy config directly, or grab the key before it is split. Full threat model.

Provided "AS IS", with no warranty of any kind, to the fullest extent permitted by law (AGPL-3.0 sections 15-16). Worthless reduces the blast radius of a leaked key on a best-effort basis; it is not a guarantee. You run it at your own risk. See LICENSE.

Quickstart

curl -sSL https://worthless.sh | sh        # fresh machine, no Python needed
# prefer to read it first?  curl -sSL 'https://worthless.sh?explain=1' | less
# or, if you already have Python 3.10+:
pipx install worthless

Then cd into your project and run worthless. It detects keys in your .env, splits them, starts a local proxy. No code changes.

The Worker emits an X-Worthless-Script-Sha256 header so you can verify the bytes you ran match the bytes the Worker advertised before piping into sh. The check catches transit/cache tampering, not origin compromise, cosign-signed release manifests for that are tracked in WOR-303.

Full install options (Docker, MCP for AI editors — Claude Code & Cursor verified, Windsurf unverified, GitHub Actions, the verified-install flow, kill-switch runbook): docs.wless.io

Scope

Worthless scans for LLM provider API key prefixes only, currently openai (sk-, sk-proj-), anthropic (sk-ant-), google (AIza), and xai (xai-). For general secret detection (cloud tokens, GitHub PATs, AWS access keys, npm tokens, Cloudflare API tokens, etc.), use gitleaks or trufflehog as a companion tool, worthless will not flag those and is not trying to replace them.

How it works

  1. worthless lock splits each API key into two shards
  2. Shard A stays on your machine (encrypted). Shard B goes to the proxy database
  3. Your .env is rewritten with shard A, format-preserving, but cryptographically useless alone
  4. The proxy reconstructs the key only when the rules engine approves the request
  5. Spend cap blown? The key never forms. The request never reaches the provider

Platforms

Platform Status
macOS Supported
Linux Supported
Windows + WSL Supported
Native Windows Not supported, use WSL or Docker

Native-Windows support is tracked in WOR-237. See docs.wless.io for the full distro support matrix.

Versioning

PyPI version, signed git tag (vX.Y.Z), and the X-Worthless-Script-Tag header on worthless.sh are kept aligned, CI fails fast if pyproject.toml and the tag disagree. By default install.sh installs a pinned worthless==<version>, the WORTHLESS_VERSION_PIN constant, hand-bumped per release like UV_VERSION and kept at the latest published release (a CI drift check fails if it falls behind), not PyPI latest, so a release compromised after yours cannot land on fresh installs. Override with WORTHLESS_VERSION=x.y.z curl -sSL https://worthless.sh | sh.

Documentation

Everything lives at docs.wless.io, install guides, the security model, wire protocol, recovery runbook, the verified-install flow, and the agent skill file (Claude Code & Cursor verified; Windsurf unverified).

For AI coding agents

Add to your project's .mcp.json (Node ≥ 18, no Python needed upfront):

{
  "mcpServers": {
    "worthless": {
      "command": "npx",
      "args": ["-y", "worthless-mcp"]
    }
  }
}

Restart Claude Code or Cursor and the MCP tools appear immediately — verified on both; Windsurf reads MCP config from its own path and is unverified. On first run, worthless-mcp bootstraps uv and installs the Python package automatically. Install time < 30 s.

Available tools: worthless_status, worthless_lock, worthless_scan, worthless_spend.

See SKILL.md for the full agent discovery file.

Development

git clone https://github.com/oblangatas/worthless && cd worthless
uv sync --extra dev --extra test
uv run pytest

Internal developer documentation lives in engineering/. Security invariants are in SECURITY.md.

Test Hardening & Repo Health

To maintain codebase health and prevent CI instability, the repository implements automated guards:

  • Thread Leak Detector: Any unit test that leaks an active background thread will fail immediately. This prevents leaked threads from contaminating subsequent tests or causing runner crashes under pytest-xdist.
  • Flaky-Test Quarantine: Flaky tests are detected at runtime and log high-visibility warnings to ensure root causes are investigated instead of swept under the rug. Quarantining a test requires a conscious human commit to tests/quarantined_tests.txt. Quarantined tests are excluded from the main blocking CI run and executed in a separate, non-blocking job.

Contributing

Pull requests welcome. Before you start, read CONTRIBUTING.md and CONTRIBUTING-security.md.

All non-trivial contributions require a signed Contributor License Agreement (CLA). The CLA grants the project the right to relicense your contribution, including under commercial terms, so the open-source code can coexist with a future paid hosted service. See CLA.md for the full text.

License

AGPL-3.0

Metadata

Release files for worthless 0.3.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for worthless 0.3.15
File Size Uploaded Provenance Actions
worthless-0.3.15.tar.gz 1.2 MB With provenance Details for worthless-0.3.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for worthless 0.3.15
File Interpreter ABI Platform Actions
worthless-0.3.15-py3-none-any.whl Python 3 none any Details for worthless-0.3.15-py3-none-any.whl

Total release size: 1.8 MB

Release files / worthless-0.3.15.tar.gz

Download URL worthless-0.3.15.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
29eab3b705acf8eb7cc770e3ef62adba84a35f722e06f63b8a6229143afb947d
BLAKE2b-256 checksum
How to use checksums
053a0b4cced182776a33eb0023b45d69fd9f43770566f9f1093da6e068d5a93a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Release files / worthless-0.3.15-py3-none-any.whl

Download URL worthless-0.3.15-py3-none-any.whl
Size 542.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0c85503546f01b44ce8af5bb07a4d90c008e41f79f7986a82f5e3e5d8d1219b8
BLAKE2b-256 checksum
How to use checksums
2aa5897770b2a20fb46987cde2dcb2c2c927500cefb0e70063a664a6654cb3b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Security for worthless 0.3.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for worthless-0.3.15.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page