Metadata-Version: 2.4
Name: skeleton-key-http
Version: 0.1.0
Summary: Skeleton Key — an HTTP access-resilience / locksmith library for Python: it presents an authentic browser TLS fingerprint and ships a portable, declarative registry of access-walls and the ranked ladder to open each one.
Project-URL: Homepage, https://github.com/veific/skeleton-key
Project-URL: Repository, https://github.com/veific/skeleton-key
Project-URL: Issues, https://github.com/veific/skeleton-key/issues
Author: Mark Bernhardt
License-Expression: MIT
License-File: LICENSE
Keywords: access-resilience,anti-bot,curl-cffi,curl-impersonate,fingerprint,http,impersonate,ja3,tls
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: curl-cffi>=0.7
Requires-Dist: platformdirs
Requires-Dist: pyyaml
Provides-Extra: browser
Requires-Dist: patchright; extra == 'browser'
Provides-Extra: dev
Requires-Dist: jsonschema; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Skeleton Key

[![CI](https://github.com/veific/skeleton-key/actions/workflows/ci.yml/badge.svg)](https://github.com/veific/skeleton-key/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://pypi.org/project/skeleton-key/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

> Your authentic browser key, for doors you're wrongly locked out of.

Skeleton Key is an access-resilience engine that presents an authentic browser
TLS fingerprint so legitimate clients aren't misclassified as bots — with a
portable, declarative registry of access-walls and the ranked ladder to open
each one.

It is built for legitimate clients that are wrongly fingerprint-blocked: your
own data and APIs behind a fingerprinting WAF, public data sources that
misclassify non-browser clients, research, archival, and accessibility tooling.

## Why

Anti-bot systems increasingly fingerprint the TLS/JA3 + HTTP/2 handshake, so a
legitimate script fetching your own data or a public API gets a challenge page
that a real browser never sees. Skeleton Key solves this honestly: it speaks an
**authentic** browser handshake via curl-impersonate (never a forged or
plain-curl one — it fails loudly rather than send a fake fingerprint), rotates
unlinkable identities when an IP or profile is burned, and — uniquely — ships a
Sigma/YARA-style portable registry: declarative YAML that detects an access-wall
and derives the ranked ladder of tools to open it.

Skeleton Key **never mutates your machine** to get in — no system tweaks, no
installed root certs, no background daemon. It opens a door from inside the
process and nothing else.

When a door genuinely cannot be opened, Skeleton Key says so. It never passes a
challenge page, a stale archive, or an alternate-route copy off as the real,
fresh resource. A wall it detects but cannot pick is reported as
*detected-but-not-solved*, never silently degraded. **Honesty is the feature.**

## Install

```bash
pip install skeleton-key
```

## Quick start

```python
from skeleton_key import open_door

result = open_door("https://www.cloudflare.com/cdn-cgi/trace")
print(result.opened, result.opened_by, result.resp.status_code)
```

This top-level `open_door` is the registry loop: it presents the authentic key and
walks the ranked tumbler→pick ladder against the front door. `result.resp` is always
the real front door — it does not rotate identity on its own or fall back to an
alternate route. For the opt-in ladder that adds identity rotation, a browser
last-resort, and labeled alternate-route shims (each stamped with source, fidelity
class, and as-of timestamp), import `from skeleton_key.shims import open_door` — see the
[Quickstart](docs/QUICKSTART.md#two-open_doors-which-one-you-get).

Or from the command line:

```bash
python -m skeleton_key https://www.cloudflare.com/cdn-cgi/trace
```

## Responsible use

Skeleton Key is a tool, in the same category as curl-impersonate, curl_cffi, and
FlareSolverr. TLS impersonation itself is legal; what you do with the access is
your responsibility. Be rate-limit aware, treat a site's Terms of Service and
`robots.txt` as a stance worth respecting, and point it at things you have a
right to reach — your own data and APIs, public data, research, and archival.
See [ETHICS.md](ETHICS.md). This is not legal advice.

## Status

Young project (v0.1). The portable registry format is the novel part; the
*content* is small (a handful of tumblers and picks) and grows by contribution.
Vendor challenges (e.g. Cloudflare Turnstile, DataDome) are detected but not
claimed solved.

## License

MIT — see [LICENSE](LICENSE).
