skeleton-key-http 0.1.0__tar.gz

skeleton_key_http-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+*.bak-*
+.skeleton_key_cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+site/
+_site/

skeleton_key_http-0.1.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to **Skeleton Key** are documented here.
+
+> Naming note: during initial development this project carried the working name
+> `skeleton-key`; it ships as **Skeleton Key** (`pip install skeleton-key`,
+> `import skeleton_key`). No `skeleton-key` identifiers remain in the code.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Until `1.0.0`, the public API and the registry schema may change between minor
+versions. Breaking changes are called out explicitly in each entry.
+
+## [Unreleased]
+
+Nothing yet. See [ROADMAP.md](ROADMAP.md) for what is planned next.
+
+## [0.1.0] - 2026-05-30
+
+Initial scaffold — the first packaged extraction of the access-resilience engine
+into a standalone, src-layout library under the import name `skeleton_key`.
+
+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.
+
+### Added
+
+- **The registry — the killer feature.** A Sigma/YARA-style portable signature
+  format for anti-bot walls: declarative YAML that detects an access-wall
+  (a *tumbler*) and binds the tools that open it (*picks*), with a **derived,
+  cannot-drift detection-to-remediation matrix**. Ships **12 tumblers** across
+  five categories (`cryptographic`, `challenge`, `temporal`, `reputation`,
+  `behavioral`) and **6 reference picks** (`header.negotiate`, `timing.backoff`,
+  `wrench.rotate_profile`, `wrench.swap_egress`, `solver.reddit_js`,
+  `browser.js_runtime`). The match-DSL semantics in `registry/detect.py` are the
+  interop contract; a JSON-Schema (`draft 2020-12`) ships the structural contract.
+- **Impersonate-only transport — the key.** TLS/JA3 + HTTP/2 mimicry via
+  `curl_cffi` with a CLI cascade (curl-impersonate). It raises `FetchError` rather
+  than ever fall back to a plain `urllib`/`requests`/`curl` path: Skeleton Key fails
+  loudly instead of sending a forged or non-authentic fingerprint. Includes a
+  cookie cache and the `fetch_raw` seam that surfaces the raw response so detection
+  lives in the registry, not the transport.
+- **Resilience layer.** Identity rotation (`Egress` / `Identity` / `Pool`) that
+  mints fresh identities by rotating egress, impersonation profile, and headers,
+  with a bounded swap loop, jittered backoff that honors `Retry-After`, and a
+  block detector. Egress sources are free/owned-only and env-gated
+  (`direct` / `warp` / `tor` / `proton`), documented with their honest tradeoffs.
+  An optional patchright browser fallback (`[browser]` extra) is the last-resort
+  rung.
+- **Shim layer.** A fidelity-ordered, last-resort alternate-route layer
+  (underlying endpoint → reader proxy → alt frontend → Wayback archive) that fires
+  **only after** picks, rotation, and the browser pass are exhausted. Every shim
+  result carries its source, fidelity class, and as-of timestamp; a non-equivalent
+  route is reported as a structural miss, never passed off as the real resource.
+- **One-import public API.** `from skeleton_key import open_door` runs the registry's
+  *matrix-only* drive loop — fetch → detect → pick → re-detect — and returns an
+  `OpenResult` exposing `.opened`, `.opened_by`, and the underlying response. The
+  **shim-aware** pipeline (shims-only-after-picks) is a distinct function in a
+  separate module, `skeleton_key.shims.open_door`, for when an honestly-labeled
+  last-resort alternate route is acceptable.
+- **The honesty contract, enforced in code.** Four invariants — impersonate-only,
+  shims-after-picks, fidelity-labeling, and no-silent-degradation — each tied to
+  the code location that enforces it. Skeleton Key fails closed on auth gates
+  (`401` / `407`) and on challenges that require a human, and labels everything else.
+- **Extensibility on-ramp.** A drop-in overlay (`contrib_example.yaml`) and a pick
+  template demonstrate that adding a wall is often data, not code: append a tumbler,
+  append a pick manifest, optionally add a handler — the matrix re-derives and the
+  loader validates the whole registry at startup.
+- **Cache-path parameterization.** A `_paths` module resolves the cache directory
+  from `$SKELETON_KEY_CACHE` if set, else `platformdirs.user_cache_dir("skeleton_key")`,
+  decoupling the library from any host-specific location.
+- **Project scaffolding.** `pyproject.toml` (src-layout, MIT, py3.10+), an offline-by-
+  default pytest suite (match-DSL golden tests, registry load-time validation, matrix
+  ranking, drop-in overlay, the impersonate-only and shim-equivalence guards, and a
+  banned-vocabulary check), a CI workflow, pre-commit hooks, docs, runnable examples
+  against defensible targets, and the responsible-use / contributing / security /
+  conduct docs.
+
+### Benchmark (point-in-time)
+
+- On a one-off run dated **2026-05-30**, Skeleton Key opened **22 of 24** tested doors
+  where plain curl (user-agent spoof only) failed on every one — the TLS/JA3 + HTTP/2
+  mimicry was the load-bearing difference. The remaining **2 were BOTH_BLOCKED**:
+  IP-gated and auth-gated, **not** fingerprint-gated, so Skeleton Key does **not** open
+  any arbitrary door. Numbers are point-in-time (sites change their posture; one site
+  shifted from an IP gate to a challenge within a day) and are re-run periodically.
+  See [docs/benchmarks.md](docs/benchmarks.md) for the dated, caveated table and the
+  defensible-targets stance in [RESPONSIBLE_USE.md](RESPONSIBLE_USE.md).
+
+### Notes on scope (honest limits at 0.1.0)
+
+- The format is **portable by construction** — language-agnostic YAML plus a
+  JSON-Schema contract — but there is **one** engine today (this Python one) and
+  **no second-language implementation yet**, so portability is a design property,
+  not a proven one.
+- Vendor challenges (Cloudflare Turnstile, DataDome, Akamai, PerimeterX, Imperva)
+  are **detected** but only carry a generic browser-pick ladder; they are **not**
+  claimed as solved. The bundled patchright pass does not pass Cloudflare Turnstile,
+  even headful.
+- The cookie cache is shared per-domain (not per-identity), and all egress is
+  `en-US`-only today. The docs state these limits rather than imply isolation or
+  geo-diversity the code does not deliver.
+
+[Unreleased]: https://github.com/veific/skeleton-key/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/veific/skeleton-key/releases/tag/v0.1.0

skeleton_key_http-0.1.0/LICENSE

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

skeleton_key_http-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+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).

skeleton_key_http-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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).

skeleton_key_http-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,191 @@
+# Architecture
+
+> **Skeleton Key** — *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.
+
+This document explains how that engine is built: the three layers and where each one's responsibility starts and stops, the `open_door` data flow end to end, and — the load-bearing claim — exactly how the *impersonate-only* invariant holds **by construction** rather than by discipline.
+
+If you want the vocabulary first (door, key, tumbler, pick, shim), read [CONCEPTS.md](CONCEPTS.md). If you want the killer feature — the portable signature format — read [REGISTRY_FORMAT.md](REGISTRY_FORMAT.md). If you want the promises Skeleton Key makes about never lying to you, read [honesty-contract.md](honesty-contract.md). This file is the map that ties them together.
+
+---
+
+## 1. The layered system
+
+Skeleton Key is three layers with strict, one-directional responsibility boundaries. Each layer knows only about the one beneath it; nothing reaches up.
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│  skeleton_key.registry          THE FORMAT — the declarative, portable engine    │
+│    data/*.yaml              tumblers (detection rules) · picks (manifests)    │
+│    detect.py                the match-DSL evaluator → which tumbler fired     │
+│    engine.py                load + validate + derive matrix + open_door loop  │
+│    handlers.py              the per-language pick bindings (the only          │
+│                             language-bound file)                              │
+├────────────────────────────────────────────────────────────────────────────┤
+│  skeleton_key.resilience        RESILIENCE — unlinkable-identity rotation         │
+│    identity.py              Egress / Identity / Pool, minting identities      │
+│    fetch.py                 the rotation drive loop + is_blocked()            │
+│    browser.py               the patchright last-resort browser fallback       │
+├────────────────────────────────────────────────────────────────────────────┤
+│  skeleton_key.transport         MECHANISM — the KEY: impersonate-only transport   │
+│    fetch.py                 curl_cffi → CLI cascade · cookie cache ·          │
+│                             fetch_raw seam · the FetchError boundary          │
+│    solvers.py               the AccessSolver registry (one reference solver)  │
+└────────────────────────────────────────────────────────────────────────────┘
+         (above) ── skeleton_key.shims ── the labeled last-resort alternate-route layer
+```
+
+A fourth module, `skeleton_key.shims`, sits beside the registry rather than inside the stack: it is tried **only after** the whole pick ladder is exhausted, and it walks to a *sibling* door (a syndication endpoint, a reader proxy, an alternate frontend, a Wayback archive) for the same content. It never touches a front-door tumbler. The canonical public entry point — `from skeleton_key import open_door` — is the registry's *matrix-only* drive loop; the **shim-aware** loop is a separate function living in this fourth module, `skeleton_key.shims.open_door`, which runs the registry pipeline first and only then considers a labeled shim. They are different modules, not two names for one loop. See [§5](#5-the-public-entry-point).
+
+### 1.1 Responsibility boundaries — where each layer stops
+
+The discipline that keeps the design honest is *what each layer refuses to do*.
+
+| Layer | Owns | Does **not** own |
+|---|---|---|
+| **transport** (mechanism) | The authentic TLS/JA3 + HTTP/2 handshake. The `curl_cffi → CLI` cascade. The cookie cache. `fetch_raw` (the raw, single-attempt, no-solver primitive). The `FetchError` boundary. | *Which* wall it hit. *What* to try next. *Where* it exits (egress is not its concern). |
+| **resilience** (resilience) | `Egress` / `Identity` / `Pool`. Minting fresh, unlinkable identities (new exit IP + profile + headers). The bounded rotation loop. `browser_fetch` (the patchright fallback). `is_blocked()`. | The taxonomy of walls. The escalation *order*. The transport mechanism itself (it delegates down). |
+| **registry** (the format) | The tumbler taxonomy. The pick catalog. The derived tumbler→pick **matrix**. The `open_door` drive loop. The match-DSL semantics (the interop contract). | The bytes on the wire — every fetch and re-fetch delegates downward. A second transport. |
+| **shims** (last resort) | The four fidelity-ordered alternate routes. The structural equivalence gate. Fidelity + freshness labelling. | Anything the picks can do. It never runs unless the picks are exhausted, and it never claims a sibling route is the real door. |
+
+The registry **consumes** the two lower layers — transport and resilience — and never reimplements transport. It does **not** consume the fourth row, `shims`: the registry's own `open_door` is front-door-only and never reaches the shim layer — that wiring lives solely in the separate `skeleton_key.shims.open_door` loop (see [§5](#5-the-public-entry-point)). A pick that needs a fresh exit IP calls into `skeleton_key.resilience`'s pool; a pick that needs a real browser calls `browser_fetch`; **every** re-attempt — without exception — goes back through the transport's impersonate-only path. That single fact is what makes the impersonate-only invariant structural rather than aspirational ([§4](#4-the-impersonate-only-invariant-by-construction)).
+
+### 1.2 Why three layers (and not one)
+
+The split exists so that each concern can be reasoned about — and tested — in isolation:
+
+- **Mechanism** can be proven impersonate-only without knowing anything about walls or rotation. It has exactly one job and one escape (`FetchError`).
+- **Resilience** can rotate identities without knowing the wall taxonomy — it only needs `is_blocked()` to tell it *whether* to rotate, not *why*.
+- **The registry** can grow new walls and tools as **data**, never touching mechanism or resilience code. Adding a wall is a YAML append, not a control-flow edit scattered across files. This is the property that makes the format portable and the contribution flywheel possible.
+
+---
+
+## 2. The `open_door` data flow
+
+`open_door` is the data-driven drive loop. It replaces what used to be a hardcoded escalation `while`-loop with one that asks the **derived matrix** what to try and in what order. The control flow is fixed and small; all the *knowledge* lives in the YAML.
+
+```
+door (url)
+  │
+  │  fetch_raw(url)              ← KEY (authentic TLS) + WRENCH (impersonation profile),
+  ▼                                NO hidden solver — the raw response, wall and all
+ Resp ──────► detect(resp, tumblers)         ← match-DSL, evaluated highest-severity-first;
+  │                  │                          the first tumbler that matches wins
+  │                  ▼  TumblerHit (id, category, severity)
+  │           resolve(matrix, hit)            ← the ranked picks for THIS tumbler (derived data)
+  │                  │
+  │                  ▼  [pick₁, pick₂, …]     exact-target → cheapest → … → heavy (browser)
+  │           handler(ctx) → Resp | None      ← the PICK acts; re-attempts only via
+  │                  │                           ctx.refetch (= fetch_raw, impersonate-only)
+  │                  ▼
+  └──────────  re-detect on the new Resp ──────► escalate to the next *untried* pick
+                                                 repeat until OPEN (no tumbler fires)
+                                                 or the picks are exhausted
+```
+
+The loop is bounded by `max_rounds` (default 6). Each round does exactly one thing: detect the current wall, resolve its ranked picks, apply the first one not yet tried, then re-detect on whatever came back.
+
+### 2.1 Step by step
+
+**1 — `fetch_raw` (the seam).** The door is fetched through the transport's `fetch_raw`: a single impersonated attempt with **no access-solvers and no escalation**. This is deliberate. The raw response — challenge page and all — is exactly what the registry needs to *see*, so detection happens in the registry where it is declarative and inspectable, not invisibly inside the transport. This is the **`fetch_raw` seam**: the transport surfaces the raw tumbler upward instead of quietly solving it.
+
+**2 — `detect`.** The response is run against the loaded tumblers, sorted highest-severity-first. Each tumbler is a match-tree (pure data; see [REGISTRY_FORMAT.md](REGISTRY_FORMAT.md)). The first tumbler that matches wins and yields a `TumblerHit` carrying the tumbler's id, category, and severity. Severity-ordering is why a specific named wall (say `challenge.reddit_js`) is checked before a generic fallback (`reputation.forbidden`) — the specific rule gets first refusal. If **nothing** matches, the door is open and the loop returns immediately.
+
+**3 — `resolve`.** Given the hit, `resolve` returns the picks that address it — already ranked — from the **derived matrix** ([§3](#3-the-derived-matrix)). This is a dictionary lookup, not a search: the ordering was computed once at load time.
+
+**4 — the pick acts.** The loop takes the first ranked pick **not yet tried this round** and calls its bound handler with a `PickContext` (the url, the current response, the hit, and — critically — `ctx.refetch`). The handler does its work and returns either a new `Resp` or `None`. `None` means *this pick could not help*; the loop records that and moves to the next untried pick. A handler that raises is caught, logged in the trace, and treated as no-help — one failing pick never aborts the door.
+
+**5 — re-detect and escalate.** If the pick returned a new response, the loop re-runs `detect` on it. If no tumbler fires, the door opened and the result is returned with `opened_by` set to the pick's id. If a tumbler still fires, the loop escalates to the next untried pick and repeats. Because each pick is marked tried, the ladder always makes forward progress and terminates.
+
+**6 — termination.** The loop ends when the door opens, when every matching pick has been tried (`exhausted`), or when `max_rounds` is reached. The return value is an `OpenResult(resp, opened, hit, opened_by, trace)`. The `trace` is the round-by-round record — tumbler hit → pick chosen → outcome — so a caller can see exactly how the matrix resolved, which is invaluable both for debugging and for trust.
+
+### 2.2 When the key itself fails
+
+If the very first `fetch_raw` raises `FetchError` — meaning every impersonation backend failed, typically a TLS-handshake-level refusal — the loop does **not** crash and does **not** fall back to a plain request. Instead it synthesizes a `cryptographic.handshake` tumbler hit and routes *that* through the same matrix. The cryptographic category's ranked picks are exactly the right response to a refused handshake: rotate the tension wrench (a different impersonation profile = a different JA3) or swap egress (a different exit IP). A key failure is just another tumbler, handled by the same uniform machinery. (If the registry somehow has no cryptographic tumbler to synthesize, the `FetchError` is re-raised honestly rather than swallowed.)
+
+---
+
+## 3. The derived matrix
+
+The tumbler→pick matrix is the heart of the registry, and its defining property is that it is **derived, never authored**. No human writes "for wall X, try pick A then pick B." The matrix is computed from the picks' declared `targets` and `cost` at load time, and it is never persisted — so it cannot drift out of sync with the data it came from.
+
+For each tumbler, every pick that *could* address it is collected and ranked by this key:
+
+1. **Exact-target first.** A pick whose `targets` names this tumbler's id is purpose-built domain knowledge — it is tried before any broad pick. (A pick targeting `cat:<category>` or the wildcard `*` is "broad".)
+2. **Then cost** (`light` < `moderate` < `heavy`). Among the broad picks, cheapest first — so fast attempts fail fast before the heavy browser render is ever spun up. You don't launch a headless browser to solve something a header negotiation would have cleared.
+3. **Then latency, specificity, and id** — stable, deterministic tie-breaks, so the same registry always produces the same ladder.
+
+This is why the ordering is trustworthy: it is a pure function of declared facts. Add a new, cheaper pick that targets a category, and it slots into *every* wall in that category at the right rung automatically — no matrix edit, no risk of a stale hand-written ladder. The matrix is introspectable at runtime (`get_registry().matrix`), which is how `examples/03_add_a_custom_pick.py` prints each tumbler's ranked ladder without making a single network call.
+
+---
+
+## 4. The impersonate-only invariant, by construction
+
+This is the project's spine, and the architecture is arranged so that the invariant holds **by construction at the top, not by discipline.** The claim is precise: there is no code path, anywhere in the engine, that sends a request without an authentic browser fingerprint — and that is true because of *how the modules are wired*, not because every contributor remembers a rule.
+
+Here is the argument, layer by layer.
+
+**The transport is the only thing that opens a socket.** All outbound HTTP in Skeleton Key funnels through `skeleton_key.transport`. Its fetch functions try the impersonation backends in a fixed cascade and nothing else:
+
+```
+curl_cffi   →   curl-impersonate CLI wrapper   →   raise FetchError
+```
+
+Both backends speak an authentic browser TLS/JA3 + HTTP/2 handshake. The cascade only ever escalates *between impersonation backends*. When both fail, it raises `FetchError` — it **never** falls through to `urllib`, `requests`, or plain `curl`. Failing loudly is the designed behavior: a plain-curl request would carry a non-authentic fingerprint that could both fail anyway and reveal the caller, so the transport refuses to send one. The raw `fetch_raw` cascade is the same three lines: `_via_cffi → _via_cli → FetchError`, with no fourth option to add a plain path.
+
+**Every re-attempt is forced back through that transport.** A pick handler does not get a raw socket or an HTTP client of its own. It receives a `PickContext` whose only fetch capability is `ctx.refetch` — and `ctx.refetch` is a thin closure over `fetch_raw`. So a pick *cannot* make a non-impersonated request even if it wanted to; the only fetch primitive it is handed is the impersonate-only one. This is the structural core: the registry's drive loop fetches via `fetch_raw`, and picks re-fetch via `ctx.refetch` which *is* `fetch_raw`. There is no second door.
+
+**The handler contract removes the temptation.** A handler that cannot help returns `None`; it never fabricates a `Resp` and never reaches for an alternate transport. The resilience layer's most invasive tool — the patchright browser — is itself a real browser, so it satisfies the invariant trivially. The contributor starting point (`examples/03_add_a_custom_pick.py`) bakes this in: the `@handler` skeleton a new author copies already routes through `ctx.refetch` and returns `None` on failure.
+
+**The boundary is enforced, not just documented.** A static test (`tests/test_impersonate_only.py`) asserts that the transport module does not import any plain-fetch library, and that the cascade raises `FetchError` rather than degrade. Because *all* fetching is concentrated in one module with one cascade, that single check covers the whole engine. You cannot satisfy the test and also smuggle in a plain path, because there is exactly one path to audit.
+
+The result: impersonate-only is a property of the module graph. To break it you would have to add a brand-new transport and rewire the drive loop and the pick context to use it — a change no honest pick needs and that the test suite and the responsible-use contract both reject.
+
+### 4.1 The auth-gate carve-out (honest, not a loophole)
+
+One subtlety preserves honesty rather than violating it. The transport's block detector deliberately carves out **`401` and `407`** as *credential-shaped* responses, not fingerprint walls. A `401 Unauthorized` or `407 Proxy Authentication Required` means the door wants credentials you don't have — rotating a profile or swapping an exit IP will never help, because the wall isn't about *what you look like*, it's about *who you are*. So the engine fails **closed** on these immediately instead of grinding through the whole ladder pretending an identity swap could open an account gate. This is the honesty contract in action: Skeleton Key does not waste your rate budget on a door it structurally cannot open, and it does not pretend an auth gate is a fingerprint problem. (See [honesty-contract.md](honesty-contract.md) for the full fail-closed posture, including human-CAPTCHA.)
+
+---
+
+## 5. The public entry point
+
+Two `open_door` functions exist, and the distinction matters:
+
+- **`skeleton_key.open_door`** (the canonical public one) — the **matrix-only** drive loop described in [§2](#2-the-open_door-data-flow). Fetch → detect → resolve → pick → re-detect → escalate. It opens a door by *picking its tumblers*, and it stops there: the real front door or an honest "stuck", no alternate routes. This is what most callers want, and the loop the example below shows.
+- **`skeleton_key.shims.open_door`** — the **shim-aware** loop, a separate function in a separate module. It runs the full registry pipeline first, and only if the picks are genuinely exhausted does it consider a labeled last-resort shim to a sibling door. Reach for it when an honestly-labeled alternate route is acceptable. (Note: these are two different modules — there is no `skeleton_key.registry.open_door`; `registry/` is data-only YAML + JSON.)
+
+```python
+from skeleton_key import open_door
+
+r = open_door("https://api.github.com")     # a defensible public API
+print(r.opened)        # True
+print(r.opened_by)     # the pick id that cleared it, or None if it was already open
+print(r.resp.status_code)
+```
+
+The ordering — **picks before shims, always** — is an architectural invariant, not a runtime preference. A shim is the last thing tried, it walks to a different URL for the same content, and whatever it returns is stamped with its fidelity class and an as-of timestamp. A non-equivalent route is reported as a structural MISS, never quietly passed off as the real, fresh resource. The shim layer's full equivalence-gating and labelling rules live in [honesty-contract.md](honesty-contract.md).
+
+---
+
+## 6. Honest caveats, per layer
+
+An architecture document that only listed strengths would itself violate the honesty contract. Here is what each layer does **not** yet deliver, stated plainly.
+
+- **Transport.** The cookie cache is keyed per registered domain and is **shared** across the toolkit's worker threads (read-mostly). It is not a per-identity, isolated cookie jar — so the cache is a point of linkage, and no part of Skeleton Key claims otherwise. The domain key uses a simple registered-domain derivation; exotic multi-label public suffixes are a known sharp edge.
+- **Resilience.** Identity rotation freshens the exit IP, the impersonation profile, and the headers — but because the cookie cache is shared per domain (above), rotation does not yet deliver *cookie-state* unlinkability. All bundled egress sources resolve to **US** exits today, so there is no geographic diversity to claim. The egress options carry honest tradeoffs (a datacenter exit is blocked *more* often than a residential one; some anonymity-network exits are themselves widely blocked) — see [egress.md](egress.md). The identity pool's thread-safety is documented, not assumed.
+- **Registry.** The *format* is novel and designed to be portable by construction — but there is **one** engine (this Python one) today and no second-language implementation, so portability is a design property, not a proven fact. The shipped content is small and honest about it: a handful of tumblers and picks at v0.1, framed as "a novel portable format," never "comprehensive coverage."
+- **Shims & vendor challenges.** Several commercial challenge systems are **detected** but only addressable by the heavy browser pick, which does not reliably open them even headful — they are honestly marked *detected-but-gap*, never "solved." When the picks and the browser both come up short, a shim to a sibling door is the labeled last resort, and a third-party reader/mirror/archive route always carries its intermediary-trust caveat.
+
+The measured result Skeleton Key stands behind, and leads with: **22 doors opened where a plain User-Agent-spoofed request failed on every one; 2 doors `BOTH_BLOCKED`** — IP- or auth-gated, not fingerprint-gated, so neither the authentic key nor identity rotation could open them (point-in-time, 2026-05-30; see [benchmarks.md](benchmarks.md)). The TLS/JA3 mimicry is the load-bearing difference on the 22; the 2 are the proof that Skeleton Key does not open *every* door, and would never claim to.
+
+---
+
+## See also
+
+- [CONCEPTS.md](CONCEPTS.md) — the lockpicking vocabulary, with a worked example per term.
+- [REGISTRY_FORMAT.md](REGISTRY_FORMAT.md) — the match-DSL, the tumbler/pick shapes, the derived matrix, and the JSON-Schema contract.
+- [honesty-contract.md](honesty-contract.md) — the four invariants and the code locations that enforce each one.
+- [egress.md](egress.md) — the identity-rotation egress catalog and its honest tradeoffs.
+- [benchmarks.md](benchmarks.md) — the dated, caveated results table.
+- [RESPONSIBLE_USE.md](https://github.com/veific/skeleton-key/blob/main/RESPONSIBLE_USE.md) — who Skeleton Key is for, and the access-resilience-not-evasion stance.