Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
344d94b
docs(spec,plan): fold in Muse's review notes on the teach recorder
cycle-five Nov 18, 2026
0982430
docs(plan): settle six plan defects found before the teach recorder b…
cycle-five Nov 18, 2026
c659227
feat(recording): typed recording format for teach mode (#361)
cycle-five Nov 18, 2026
88c9314
docs(plan): tag Shape with kind, like the other tagged enums
cycle-five Nov 18, 2026
9c63670
refactor(recording): tag Shape with kind and round-trip every variant…
cycle-five Nov 18, 2026
c6a265c
feat(recording): classify a recorded login by shape and rung ceiling …
cycle-five Nov 18, 2026
4340733
feat(teach): markers and their search over request bytes (#361)
cycle-five Nov 18, 2026
056ca5a
feat(teach): find a marker in a host name without regard to case (#361)
cycle-five Nov 18, 2026
6416646
feat(teach): strip URLs and reduce request bodies to shapes (#361)
cycle-five Nov 18, 2026
e78daad
fix(teach): find percent-encoded values by decoding the haystack (#361)
cycle-five Nov 18, 2026
4931542
docs(plan): strip_url takes the pair, and one shared no-typed-value c…
cycle-five Nov 18, 2026
2ad42b8
fix(teach): match typed values across separators and letter case in k…
cycle-five Nov 18, 2026
b5e8dff
feat(teach): capture state machine from events to a stripped recordin…
cycle-five Nov 18, 2026
ef6b532
fix(teach): match typed values across URL parts, and short ones only …
cycle-five Nov 18, 2026
035f70e
fix(teach): tighten capture's kept text, username choice and memory b…
cycle-five Nov 18, 2026
ea31220
feat(teach): launch a browser on a private throwaway profile (#361)
cycle-five Nov 18, 2026
b5e6389
fix(teach): a profile names its owner so a sweep never takes a live o…
cycle-five Nov 18, 2026
ebf70f1
feat(teach): a CDP client that subscribes to events (#361)
cycle-five Nov 18, 2026
0d3491d
fix(teach): sweep tests use private directories; guard the first URL …
cycle-five Nov 18, 2026
9711369
fix(teach): zeroize CDP frame text and bound every wait (#361)
cycle-five Nov 18, 2026
63dfdda
feat(teach): record a login from a live browser session (#361)
cycle-five Nov 18, 2026
7319ec4
feat(teach): kharon-teach command line, consent and the recording fil…
cycle-five Nov 18, 2026
2a86a5e
fix(teach): selectors, world probe, post data and group cleanup for t…
cycle-five Nov 18, 2026
776b3d0
fix(teach): exit without waiting on stdin; tighter scans and file han…
cycle-five Nov 18, 2026
671a0ff
docs(spec): REQ-TCH rows and the teach-mode user page (#361)
cycle-five Nov 18, 2026
56d2cc2
docs(spec): make the REQ-TCH rows and the user page say what is built…
cycle-five Nov 18, 2026
950e091
fix(teach): sweep only profiles we made; clean up on hangup and quit …
cycle-five Nov 18, 2026
ab58661
fix(teach): keep a name only when it looks like one; never lose a hit…
cycle-five Nov 18, 2026
8072467
fix(teach): cross-site only before the password is sent; confident hi…
cycle-five Nov 18, 2026
9e05de0
fix(teach): bound the work and the output a page can cause (#361)
cycle-five Nov 18, 2026
e766387
fix(teach): honest messages, a panic hook, snap browsers and safe sho…
cycle-five Nov 18, 2026
ab5a1d4
docs(spec): bring the REQ-TCH rows and the user page up to the final …
cycle-five Nov 18, 2026
3c14c67
fix(teach): give the path dependency a version, as cargo deny requires
cycle-five Nov 18, 2026
1cb3f7b
fix(teach): encoded host labels, a real CSS unescape, cross_site word…
cycle-five-duet[bot] Nov 19, 2026
61d9ecb
docs(spec): REQ-TCH-003 says opaque bodies keep length and markers (#…
cycle-five Nov 20, 2026
59291d7
fix(teach): replace IDN host labels holding typed values (#364)
cycle-five Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ members = [
"crates/kharon-cli",
"crates/kharon-connector",
"crates/kharon-agent-connector",
"crates/kharon-recording",
"crates/kharon-teach",
]

# SPEC §8 process hardening: a release build aborts on panic instead of
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ Vaultwarden fill broker: lets AI agents fill credentials without ever seeing the
- [`docs/broker-lifecycle.md`](docs/broker-lifecycle.md): host install of kharond, backup and restore of `/data`, upgrades, and the secrets inventory.
- [`docs/vault-onboarding.md`](docs/vault-onboarding.md): the customer's Bitwarden organization, collection, dedicated account, and API key.
- [`docs/agent-runtime-setup.md`](docs/agent-runtime-setup.md): the agent side on a hosted or root runtime, and handing over credentials.
- [`docs/teach-mode.md`](docs/teach-mode.md): `kharon-teach`, a program that records how a login works while a person logs in by hand with a throwaway account, and writes a file with no typed value in it (#361).
- [`docs/hermes-end-to-end.md`](docs/hermes-end-to-end.md): Hermes after the connector is installed: the MCP client, what the agent and the owner do in a fill, and what each failure looks like. A record of one live run.
- [`docs/acceptance-checks.md`](docs/acceptance-checks.md): checks a new managed deploy must pass before it carries anyone but a pilot (edge, one real fill, REQ-GOAL-002 canaries).
- [`deploy/compose/README.md`](deploy/compose/README.md): running kharond with Docker Compose.
Expand Down
13 changes: 13 additions & 0 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,19 @@ The agent keeps its own CDP session (Playwright/puppeteer `connectOverCDP`). kha
| REQ-ARCH-005 | Target ownership. The broker creates one browser context per agent (`Target.createBrowserContext`) and hands the agent its `browserContextId` via `kharon_context` / `POST /v1/context` (#65): the call connects if needed (the broker stays lazy, no connect at startup), creates or returns the agent's cached context, and replies `browser_context_id`. It is idempotent while the CDP connection lives; a reconnect or a lock invalidates the id (the next call returns a new one, and fills into tabs of the old context get `target_not_owned`). It is lock-gated (`423` while locked), runs under the `fill_deadline`, and is audited like a fill (`context_open` before any CDP write, then exactly one `context` outcome; REQ-AUD-003†). `kharon_status` reports the cached id or `null` and never connects. `fill` is accepted only if `cdp_target_id` is in the requesting agent's context. Targets in the default context are refused unless `allow_default_context=true`, for single-agent setups. | E2E: agent A fills into a tab in agent B's context → `target_not_owned`. Default-context tab with the flag off → refused. Daemon + CDP stub: no connection before the first `kharon_context`; two calls → same id, one `createBrowserContext`; after a reconnect or lock+unlock → new id; `423` while locked; `status.browser_context_id` is `null` before the first call and after invalidation. |
| REQ-ARCH-004 | Chromium launched with password manager and autofill save disabled. | Profile `Login Data` contains 0 rows after 10 fills. |

### 3.4 Teach mode: recording a demonstrated login

`kharon-teach` is a separate program. A person runs it on their own computer, with a throwaway account, to show kharon how one site's login works. It opens its own visible browser, reads what the page does while the person logs in by hand, and writes one file that describes the structure of the login. The file holds no typed value. It shares nothing with a fill: it has no broker credential, no vault access and no connection to a broker. It needs to hear what the page does, so its CDP client enables the `Runtime`, `Network` and `Page` domains. The broker's client enables none of them (REQ-ARCH-003). The recorder therefore has its own client and never uses the broker's. Turning a recording into a login method, and replaying one, is later work (#361). The design is in [`docs/superpowers/specs/2026-11-18-teach-recorder-design.md`](docs/superpowers/specs/2026-11-18-teach-recorder-design.md). The user page is [`docs/teach-mode.md`](docs/teach-mode.md).

| ID | Requirement | AC |
|---|---|---|
| REQ-TCH-001 | The recorder launches the browser itself, in its own process group, on a profile directory it created (mode `0700`, with an owner file). It has no option to attach to another browser or to name a profile. The browser's debugging port is loopback only. | `crates/kharon-teach/tests/req_tch_001_own_browser.rs`: a launched browser runs with `--user-data-dir` set to the profile the recorder made, and the debugging port listens only on loopback. A scan of the shipped source finds no `ws://` or `http://` address that is not the loopback CDP one, and the fields of `Launch` are `browser`, `first_url`, `headless` and `profile`. |
| REQ-TCH-002 | No typed value is written to the recording file, to any other file of the recorder's own, or to its output. This covers every value typed in the window, not only the user name and the password. A name that contains a typed value is replaced with `{typed}` (a field or part name, a JSON key, a host label, a content type, a scheme), and the hits found in it stay on the field. A path segment that contains one is replaced with `{id}`. An element attribute or selector that holds one is left out. A value shorter than six characters is removed from kept text where it stands as a whole word, in any of its encodings. | `crates/kharon-teach/tests/req_tch_002_no_typed_value.rs`: for each of the four fixture logins, a byte search of the recording for the user name and the password, in every encoding the recorder knows, finds nothing. The same search over the whole program's file, standard output and standard error finds nothing. A page that copies a typed value into an attribute, and the listener script's own reports, carry none of it. A fifth fixture puts the typed values into a path, a query key and a JSON key: the file holds none of them, the path is `/u/{id}`, the query key and the JSON key are `{typed}`, and the hits in the key are kept. The whole-string rule, the encoded forms of short values and the name rules are checked by unit tests in `crates/kharon-teach/src/strip.rs`, `body.rs` and `marker.rs`. |
| REQ-TCH-003 | The file holds no cookie, no request or response header value other than the content type and the `Authorization` scheme (the browser's own name and user-agent string are recorded, as they are not header values the page sent), no response body, no query value and no request-body value. A field name, part name, JSON key or query key is kept only when it looks like a name (at most 64 characters of letters, digits and `_ . : - [ ]`, and not an identifier); otherwise it is written `{other}`. A body that is not what its content type says, or that would hold more than 2,000 values, is kept as `opaque`: its length and the role and encoding of each typed value found in it, never its content. A body over 1 MiB is `unavailable`. A URL scheme and an `Authorization` scheme are kept only from a known list. The content of a `data:` URL is never kept. | `crates/kharon-teach/tests/req_tch_003_file_contents.rs`: the file is mode `0600`, reads back as a recording, keeps a query key and not its value, and holds no cookie, no response text, no page title and none of eight named headers; the response's `Set-Cookie` shows only as a flag. The scheme lists and the `data:` rule are checked by unit tests in `crates/kharon-teach/src/strip.rs`. The name rule, the 2,000-value cap and the token-shaped bodies, keys and queries are checked by unit tests in `strip.rs` and `crates/kharon-teach/src/body.rs`. |
| REQ-TCH-004 | The recorder holds no broker credential, listens on no socket, and opens no network connection except loopback CDP to the browser it launched. | `crates/kharon-teach/tests/req_tch_004_no_network.rs`: the shipped source has no listener or bind call. The dependency tree has no TLS or HTTP client crate, no `kharond` and no `kharon-connector`. The only dial is in `cdp.rs`, to a `ws://127.0.0.1:` address. |
| REQ-TCH-005 | The four fixture logins classify as `form_post`, `script_post`, `two_step` and `transformed`. | `crates/kharon-teach/tests/req_tch_005_shapes.rs`: a real Chromium logs in to each of the four fixture pages, and each recording carries the shape named for it and the rung ceiling `milliseconds` (the form, script and hashed pages) or `agent_continues` (the two-step page). Further cases cover a multipart body, a blob body, a pop-up and a login in a frame. |
| REQ-TCH-006 | The browser and its profile are removed on every exit the recorder can see (confirm, discard, window closed, browser killed, SIGINT, SIGTERM, SIGHUP, SIGQUIT). A recorder killed without that chance (SIGKILL, a crash) leaves its browser window open; the profile is then removed at a later start, once that window is closed. A start removes a leftover directory only when the recorder made it: its name is `kharon-teach-` and 20 letters and digits, it is a real directory owned by the same user, its owner file names a process that is not running, and no browser is running on it. Any other directory is left alone. The browser is always visible: no flag and no environment variable changes that. | `crates/kharon-teach/tests/req_tch_006_profile_and_visible.rs`: the profile is gone after each of those exits, and no process is left with the profile on its command line after SIGINT, SIGTERM, SIGHUP and SIGQUIT, both before the browser is ready and after the end prompt. A leftover with a dead owner is removed at the next start, and directories without an owner file, with a junk owner file or with another name shape are not. After a login the browser's password and autofill tables are empty. A scan of the shipped source finds no way to ask for headless, and `PATH` is the only environment variable read. The sweep rule (name shape, owner file, live owner, live browser, symlinks) and the clearing of the browser's process group id are checked by unit tests in `crates/kharon-teach/src/browser.rs`. |

## 4. Agent-facing API

Exposed as MCP (tools below) and HTTP `/v1/*`, with identical semantics. Auth: `Authorization: Bearer kh_agent_<id>_<random32>`. Only the Argon2id hash of the token is stored. One token per agent identity. The owner mints the token out of band with `kharon token mint <id>` (§7); the daemon does not. A dashboard instead connects with MCP OAuth and calls `POST /mcp` with a short-lived access token, `kh_at_…`, issued by the deploy's own authorization server (§4.1).
Expand Down
13 changes: 13 additions & 0 deletions crates/kharon-recording/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
[package]
name = "kharon-recording"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
publish.workspace = true
description = "Typed recording format for kharon teach mode (#361)"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
Loading
Loading