@raibitsi/tiresias 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +88 -0
- package/README.md +72 -33
- package/data/README.md +33 -0
- package/data/guard-ordinary-urls.txt +102 -0
- package/data/guard-starter.jsonl +424 -0
- package/dist/aimed.js +23 -0
- package/dist/anchor.js +26 -13
- package/dist/browsecli.js +17 -13
- package/dist/cdp.js +22 -1
- package/dist/cleanup.js +3 -1
- package/dist/cli.js +216 -68
- package/dist/config.js +75 -1
- package/dist/confirm.js +20 -5
- package/dist/cooldown.js +57 -32
- package/dist/dailylog.js +11 -5
- package/dist/dom.js +13 -8
- package/dist/doors.js +1 -1
- package/dist/engine.js +9 -4
- package/dist/envelope.js +10 -1
- package/dist/fetcher.js +29 -2
- package/dist/filereply.js +7 -1
- package/dist/formflow.js +21 -3
- package/dist/forms.js +337 -42
- package/dist/getactions.js +119 -0
- package/dist/guard.js +1240 -0
- package/dist/guardclient.js +245 -0
- package/dist/guardnetwork.js +22 -0
- package/dist/history.js +11 -5
- package/dist/hook.js +2 -0
- package/dist/hosts.js +34 -27
- package/dist/keys.js +420 -18
- package/dist/local.js +537 -0
- package/dist/mcp.js +56 -25
- package/dist/needs.js +9 -5
- package/dist/parentwatch.js +6 -16
- package/dist/pdf.js +4 -1
- package/dist/pdfchild.js +0 -2
- package/dist/pdfproc.js +26 -11
- package/dist/pdfwatch.js +14 -0
- package/dist/pipeline.js +117 -26
- package/dist/preformatted.js +12 -0
- package/dist/profiles.js +3 -3
- package/dist/queue.js +24 -20
- package/dist/reader.js +441 -87
- package/dist/receipts.js +7 -2
- package/dist/render.js +156 -27
- package/dist/renderactions.js +69 -0
- package/dist/resume.js +8 -6
- package/dist/rules.js +24 -5
- package/dist/safebrowsing.js +3 -3
- package/dist/safety.js +15 -7
- package/dist/sandbox.js +1 -1
- package/dist/saved.js +24 -9
- package/dist/savedlock.js +99 -5
- package/dist/settings.js +10 -3
- package/dist/shelf.js +1 -1
- package/dist/shield.js +15 -0
- package/dist/slips.js +43 -1
- package/dist/store.js +119 -25
- package/dist/tabs.js +1 -1
- package/dist/textview.js +16 -0
- package/dist/translate.js +22 -2
- package/dist/types.js +9 -2
- package/dist/watchflow.js +1 -2
- package/dist/work.js +10 -2
- package/docs/LOCAL-MODELS.md +271 -0
- package/package.json +5 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,94 @@
|
|
|
2
2
|
|
|
3
3
|
Built from docs/SPEC.md, section 10, which has the full detail of every version.
|
|
4
4
|
|
|
5
|
+
## v1.2.0 (2026-11-19)
|
|
6
|
+
|
|
7
|
+
Local model mode. A model that runs on your own computer has little working memory, and the full server's 18 tools use about 4,000 tokens of it before the first question. `tiresias mcp --local` is one tool and the same reply with parts left out. In our tests a 9B model with 4,096 tokens of context answered 6 of 6 page questions right through it, against 0 of 6 through the full server. Three reader faults found on the way are fixed for everyone: Wikipedia articles and several other sites had been reading as empty pages.
|
|
8
|
+
|
|
9
|
+
For local models:
|
|
10
|
+
|
|
11
|
+
- `tiresias mcp --local [--local-budget n]` starts a server with one tool, `read`. Its instructions and tool list take about 200 tokens, against about 4,000. A reply is the usual envelope without the receipts list, flags, links, forms and metadata. Receipts are still written to your store. Page text is held to your budget: 6,000 characters by default, from 1,000 to 20,000.
|
|
12
|
+
- `tiresias read <address> --local` prints exactly what a local model is given.
|
|
13
|
+
- Text that looks written to steer an AI is handled before the model sees it. One sign puts a fixed warning on the passage. Two signs, or chat markers on their own, replace the passage with a fixed sentence saying text was withheld. This is best effort, and SECURITY.md says so with the test numbers.
|
|
14
|
+
- New and optional: the meaning check. `tiresias guard setup` connects your own embedding model. Each passage a local read is about to show is compared with a library of known planted instructions and with ordinary page text, and a close match counts as one more sign. It is off until you set it up. Page text goes only to the address you give. When your model is not running, the read still works and says `"meaning_check": "not run"`. In our tests it marked 13 of 24 planted comments in a first blind set, and 5 of 24 in a second set written to use different tricks, at about 1 false alarm per 100 ordinary passages. On one more blind set, written for this release, the list that ships marked 10 of 24 planted comments and none of 24 honest ones. `guard show`, `guard check`, `guard import` and `guard off` manage it.
|
|
15
|
+
- New: who wrote each passage. On a page where Tiresias finds text written by visitors (comments, reviews, answers, forum posts), each passage of a local reply carries `written_by`: the site, or a visitor to the site. Tiresias reads this from the page's own markup. It is a fact and not a warning, and nothing is withheld because of it. In lab tests with four local models it cut the planted comments a model followed from 33 to 11 of 288 tries. It is on by default, and `tiresias settings set written_by off` turns it off.
|
|
16
|
+
- When a plain read finds an empty JavaScript shell and your `rendering` setting is `ask`, a local read renders the page in the same call.
|
|
17
|
+
|
|
18
|
+
Reading pages, for everyone:
|
|
19
|
+
|
|
20
|
+
- Every English Wikipedia article had read as an empty page, and every revisit to one failed. Both are fixed.
|
|
21
|
+
- A page whose content sits inside an element named after its menu, sidebar or footer no longer reads as empty (vuejs.org, usa.gov, substack.com, kayak.com). The rule was rewritten after a fresh review: such an element is now judged on its own text. On 94 more real pages, 90 read the same and 4 gained text that had been dropped.
|
|
22
|
+
- A short complete page with a script (example.com), or a page that is a list of links, is no longer called JavaScript-only.
|
|
23
|
+
- The first page of a visit is faster. It no longer waits the default 1 second after the robots.txt request it was checked against. Measured on five real sites: 0.26 to 0.56 seconds, against 1.35 to 1.67 before. Every other pair of requests to a site is still at least a second apart, and a site's Crawl-delay or Retry-After is obeyed as before.
|
|
24
|
+
- The full server's flags use the same patterns as local mode's check, so a reworded instruction aimed at an AI is flagged in the default reply too. Nothing is withheld in the default reply.
|
|
25
|
+
|
|
26
|
+
Fixes from CodeRabbit's Deep Scan (three findings, all low):
|
|
27
|
+
|
|
28
|
+
- A robots.txt larger than 512 KB is no longer cut short and parsed. The site is taken to say no.
|
|
29
|
+
- Control characters in anything the command line prints are shown as visible text, so page text cannot send escape codes to your terminal.
|
|
30
|
+
- When a timestamp calendar reports a Bitcoin block, the text says it is that calendar's report, and the other listed calendars are still asked for 14 days.
|
|
31
|
+
|
|
32
|
+
Testing and releases:
|
|
33
|
+
|
|
34
|
+
- Local mode was tested with six local models on real pages, and the planted comment tests ran on four. The method, the numbers and the scripts to run them again are in `docs/LOCAL-MODELS.md`, `docs/v1.2/findings.md` and `scripts/v12-lab/`.
|
|
35
|
+
- The meaning check's example list is kept as two lists: `data/` is released and `data-next/` is the working list. A release ships only when the two are the same.
|
|
36
|
+
- Cached pages are read again once (`PARSER_VERSION` 20).
|
|
37
|
+
|
|
38
|
+
## v1.1.1 (2026-11-11)
|
|
39
|
+
|
|
40
|
+
Five fixes, found by CodeRabbit's first review of v1.1.0 and by the review of the fixes. Three are cases where Tiresias refused more than it needed to: they erred on the safe side, and none let a page, a site or an agent do anything. The fourth closes a gap in the same check. The fifth corrects where one unusual form is sent.
|
|
41
|
+
|
|
42
|
+
- With `get_form_actions=slip`, a Tiresias that had run long enough to see more than 4,096 GET form addresses asked for a slip on every read until it was restarted. It now keeps guarding the addresses it has seen and leaves other reads alone. After many thousands more, an unrelated address can now and then need a slip too. A private call that sees more than 4,096 of its own still needs a slip for every GET until that call ends.
|
|
43
|
+
- Rendering works on pages with many forms. A page with more than 20 forms used to have every script and data request refused. Tiresias now checks up to 1,000 forms, in the HTML and in the live page, and a script's request that matches one of their GET addresses is still refused. Past 1,000 forms and buttons with an address of their own, past 65,536 characters of addresses, or when an address cannot be checked safely, every request is refused as before. Reads still list 20 forms.
|
|
44
|
+
- A form that points at `javascript:` or `mailto:` no longer makes rendering refuse the page's scripts. A form with an unknown method now counts as a GET form in this check, as it does in browsers.
|
|
45
|
+
- Rendering now also refuses a script's request to the address a button can send its form to (`formaction`). Before, only the form's own address was checked, so a page's script could request the button's address. A NUL character inside a form address, which a browser reads differently from Tiresias, now makes the check refuse every request.
|
|
46
|
+
- A form whose address is written as blank space now goes where a browser would send it on a page that sets a base address: to that base address, not to the page. Before, the listing, the preview and the send all named the page. A slip was needed either way, and a preview made before this fix cannot be used to send. Cached pages are read again once.
|
|
47
|
+
|
|
48
|
+
## v1.1.0 (2026-11-10)
|
|
49
|
+
|
|
50
|
+
The security deep dive. Every promise in SECURITY.md was attacked end to end, the way a hostile page or a fooled agent would, and each finding was fixed with a test or written down as a known limit in SECURITY.md.
|
|
51
|
+
|
|
52
|
+
For owners:
|
|
53
|
+
|
|
54
|
+
- Four new settings, shown in `tiresias settings`. `get_form_actions` is `read` by default; `slip` makes reading an address that matches a known GET form action need a `submit_form` slip. `private_spacing` is `shared` by default, so private calls and previews now wait their turn across processes and write only the site's origin and times; `none` turns that off after confirmation. `hook_secrets` is `hidden` by default, so your scanner and translator hooks no longer receive Tiresias's own secret variables; `inherit` restores the old behavior after confirmation. `text_views` is `marked` by default, so `--text` views and the default `log` and `needs` output mark where web text begins; `wrapped` wraps it the way JSON output does.
|
|
55
|
+
- `tiresias keys rotate` gives you a new signing key while the old one stays in the directory for 7 days (`--overlap` 0 to 30). `--finish` ends the overlap early. `--slips` makes a new slip key and revokes every slip.
|
|
56
|
+
- SECURITY.md states the form promise as the code keeps it: no form is sent without your permission slip, and recognizing sign-in, payment and purchase forms is best-effort in 13 languages.
|
|
57
|
+
|
|
58
|
+
Forms:
|
|
59
|
+
|
|
60
|
+
- Purchase forms without card fields ("Pay now", checkout) and sign-in forms without a password field are now recognized and refused. Recognition is by word lists in English, Spanish, French, German, Portuguese, Italian, Dutch, Russian, Chinese, Japanese, Korean, Arabic and Hindi.
|
|
61
|
+
- A slip is checked again right before the form is sent. One that expired or was revoked while the submit waited is not used.
|
|
62
|
+
- A rendered page's scripts may not request an address that matches a GET form action on that page.
|
|
63
|
+
|
|
64
|
+
The site's rules:
|
|
65
|
+
|
|
66
|
+
- A robots.txt redirect to another site is followed only to that site's own `/robots.txt`. Anything else counts as the site saying no.
|
|
67
|
+
- Retry-After on a redirect is obeyed before the redirect is followed, for pages, robots.txt and rendered requests.
|
|
68
|
+
- A Crawl-delay longer than 30 seconds is no longer shortened to 30: Tiresias declines the read instead of waiting less than the site asked. When robots groups merge, the longest delay applies.
|
|
69
|
+
- An active Retry-After wait is not forgotten however large the cooldown log grows. If the wait cannot be read, Tiresias does not send.
|
|
70
|
+
|
|
71
|
+
Web text stays data:
|
|
72
|
+
|
|
73
|
+
- Machine translations are scanned by the injection shield. Flags stay with the reply, with snippets inside `untrusted_content`, and survive a translation dropped for size.
|
|
74
|
+
- A bookmark name chosen by an agent appears inside `untrusted_content` in `watch` replies, not beside Tiresias's own fields.
|
|
75
|
+
- Text an agent supplies to `resume` over MCP is recorded as provided by the agent, not by a person.
|
|
76
|
+
|
|
77
|
+
Secrets, files and limits:
|
|
78
|
+
|
|
79
|
+
- The Google Web Risk request gets the same private-address and port checks as every other request.
|
|
80
|
+
- The PDF child process may no longer start worker threads.
|
|
81
|
+
- Calendar files are always read in a worker thread with a time budget, whatever their size.
|
|
82
|
+
- A secret the site echoes back is looked for in the full text of an Office answer or a PDF title before anything is shortened.
|
|
83
|
+
- A page whose outline would take too long to build ends as `page_too_complex` instead of stalling other calls.
|
|
84
|
+
- Requests waiting during a render keep only a bounded set of header fields in memory.
|
|
85
|
+
- History and receipt scans stop on cancellation or at a 60 second deadline.
|
|
86
|
+
|
|
87
|
+
Testing and releases:
|
|
88
|
+
|
|
89
|
+
- An attack lab of hostile pages runs in the test suite, so every attack tried in this review stays tested.
|
|
90
|
+
- The fuzzer (`scripts/fuzz.mjs`, opt-in) gained two targets that drive the real MCP server and the form flow with malformed input.
|
|
91
|
+
- Releases are built by GitHub Actions and staged on npm through trusted publishing, with provenance and a software bill of materials. A person approves each staged version before anyone can install it, and no npm token is stored anywhere.
|
|
92
|
+
|
|
5
93
|
## v1.0.1 (2026-11-01)
|
|
6
94
|
|
|
7
95
|
- Cancelling a read while it waits its turn no longer adds extra delays to later requests.
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Status: v1.0.0, the first public release. It is tested on macOS and Linux with e
|
|
|
8
8
|
|
|
9
9
|
## Install in 30 seconds
|
|
10
10
|
|
|
11
|
-
Needs Node 22.13 or newer, on macOS or Linux. Windows is not yet supported
|
|
11
|
+
Needs Node 22.13 or newer, on macOS or Linux. Windows is not yet supported: Tiresias does not start there (its check that no other user can write to the store reads Unix permission bits).
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
npm install -g @raibitsi/tiresias
|
|
@@ -83,7 +83,7 @@ tiresias read https://example.com/anvil-care --question "how do I test rebound"
|
|
|
83
83
|
|
|
84
84
|
- **Reads pages the way an agent needs them.** An outline first, one section or the best quoted passages on request, in pages that fit a context window. Main content found and boilerplate (menus, cookie banners, related posts) dropped; tables as rows, HTML and Markdown code blocks kept as written, lists with their markers, page metadata. Markdown, JSON, PDFs, SVG and plain text too.
|
|
85
85
|
- **Uses the front door when there is one.** Asks for markdown first, reads `llms.txt` and `llms-full.txt`, and reports the MCP servers, API specs and feeds a site offers.
|
|
86
|
-
- **Is honest on every request.** Says what it is in its user agent (`Tiresias/<version> (+https://raibit.ai/tiresias/)`, a page that leads to this repo), can sign each request with Web Bot Auth so a site can verify it, obeys robots.txt, Crawl-delay and Retry-After on every site it reads, and spaces its requests to one site at least a second apart, shared by every Tiresias process on the machine (private reads and form previews
|
|
86
|
+
- **Is honest on every request.** Says what it is in its user agent (`Tiresias/<version> (+https://raibit.ai/tiresias/)`, a page that leads to this repo), can sign each request with Web Bot Auth so a site can verify it, obeys robots.txt, Crawl-delay and Retry-After on every site it reads, and spaces its requests to one site at least a second apart, shared by every Tiresias process on the machine (private reads and form previews share only the minimal politeness state, origin and times; `private_spacing=none` disables that sharing after confirmation). The one exception is the first page of a visit, which may follow the site's robots.txt straight away; a Crawl-delay the site asks for is always obeyed in full.
|
|
87
87
|
- **Stops for a person.** At a CAPTCHA, a login or a bot check it stops, gives you the page to open, and keeps a ticket so the agent can resume once you are through, or read the page you saved.
|
|
88
88
|
- **Treats the web as data.** Everything from a page sits inside `untrusted_content`; hidden text (inline styles, the page's own style rules, screen-reader-only classes, white or off-page PDF text, and on a rendered page whatever the browser does not show), invisible characters and instructions aimed at an AI in 13 languages are flagged.
|
|
89
89
|
- **Renders JavaScript-only pages, if you allow it.** In the Google Chrome you already have, with every request the page makes fetched under Tiresias's own rules (v0.7).
|
|
@@ -93,7 +93,7 @@ tiresias read https://example.com/anvil-care --question "how do I test rebound"
|
|
|
93
93
|
- **Checks for phishing first.** Every URL is checked against the Phishing.Database list (and Google Web Risk if you add a key) before it is fetched (a private session uses the list already on disk and never downloads one: run `tiresias safety update` first).
|
|
94
94
|
- **Acts only with your permission.** It can send a form only with a permission slip that you grant, at a terminal; it never pays.
|
|
95
95
|
- **Watches for changes.** `check` and `watch` say what changed since the last visit, block by block.
|
|
96
|
-
- **Stays private when asked.** Private mode keeps
|
|
96
|
+
- **Stays private when asked.** Private mode keeps no page record; the site's waits and minimal spacing state still apply.
|
|
97
97
|
|
|
98
98
|
## How it compares
|
|
99
99
|
|
|
@@ -127,10 +127,24 @@ args = ["mcp"]
|
|
|
127
127
|
|
|
128
128
|
Any other MCP app takes the same command, `tiresias mcp`, over stdio (`examples/claude-code.mcp.json` is a project-level `.mcp.json`). From a source checkout, use `node /path/to/tiresias/dist/cli.js mcp` instead.
|
|
129
129
|
|
|
130
|
-
Tools (18): `read`, `doors`, `check`, `receipts`, `history`, `log`, `needs_report`, `bookmarks`, `bookmark`, `watch`, `resume`, `handoffs`, `slips` (read only), `form_preview`, `form_submit`, and since v0.6 `tabs`, `tab` and `files` (the downloads shelf). Each has a title and the standard annotations (read-only, destructive, open-world), and the rules they share are in the server's instructions. The agent's name from the MCP handshake is recorded in history. One server runs at most 8 calls at once (32 more wait their turn; past that a call gets an error at once), 4 page parsers and 2 renders; a call's arguments are capped (1,000 values, 8 MB), and a call the server cannot run (an unknown tool, arguments that do not fit) gets a fixed error, never the caller's own words back.
|
|
130
|
+
Tools (18): `read`, `doors`, `check`, `receipts`, `history`, `log`, `needs_report`, `bookmarks`, `bookmark`, `watch`, `resume`, `handoffs`, `slips` (read only), `form_preview`, `form_submit`, and since v0.6 `tabs`, `tab` and `files` (the downloads shelf). History, receipts, log and needs scans stop on cancellation or after 60 seconds, and read only up to each file's starting end offset. Each has a title and the standard annotations (read-only, destructive, open-world), and the rules they share are in the server's instructions. The agent's name from the MCP handshake is recorded in history. One server runs at most 8 calls at once (32 more wait their turn; past that a call gets an error at once), 4 page parsers and 2 renders; a call's arguments are capped (1,000 values, 8 MB), and a call the server cannot run (an unknown tool, arguments that do not fit) gets a fixed error, never the caller's own words back.
|
|
131
131
|
|
|
132
132
|
**Memory ceiling (v0.9).** `tiresias mcp` runs the server under its own memory ceiling: `TIRESIAS_MEMORY_MB`, default 1024 MB (set it in your app's MCP `env` block; `off` turns it off). Tiresias trusts the app that starts it not to flood its own server, and keeps the limits above anyway; if a flood ever reaches the ceiling, the server stops cleanly with `Tiresias stopped: the MCP server reached its memory ceiling ...` on standard error and a line in the daily log, and your app can start it again. The ceiling covers the server's JavaScript memory. It reads the heap in the callback reporting a full garbage collection, on a later turn, so allocations since that collection count too; it also checks every second at 1.5 times the ceiling. Only two consecutive readings above their thresholds stop the server, so a single inflated reading does not stop it (a burst inside one call can pass the ceiling before a check, up to Node's own limit); page parsers, PDF readers and renders have their own caps. Do not cap the heap with `NODE_OPTIONS=--max-old-space-size` instead: Node applies that flag to the parser workers too and lifts their own 512 MB cap.
|
|
133
133
|
|
|
134
|
+
## Local models (v1.2)
|
|
135
|
+
|
|
136
|
+
A model that runs on your own computer, through LM Studio, Ollama and the like, has little working memory, and the 18 tools above cost about 4,000 tokens of it before the first question. For those models start the server with `--local`:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{ "mcpServers": { "tiresias": { "command": "tiresias", "args": ["mcp", "--local"] } } }
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
It offers one tool, `read`, and sends the same envelope with parts left out: no receipts list (receipts are still written to your store), no flag list, links, forms or metadata. A reply carries at most about 6,000 characters of page text (`--local-budget`, 1,000 to 20,000). A passage that looks written to steer an AI gets a warning on it, or is withheld when two signs agree. In our tests a 9B model with 4,096 tokens of context went from 0 right answers in 6 to 6, and a 30B model with 8,192 from 1 to 6.
|
|
143
|
+
|
|
144
|
+
If you run an embedding model too, `tiresias guard setup --url http://localhost:1234/v1 --model <id>` adds an optional meaning check: each passage is compared with known planted instructions by your own model, and a close match gets the same warning. In our tests it caught about half of the attacks it had never seen, at 1 false alarm per 100 ordinary passages (numbers in [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md)). Page text goes only to the address you give it.
|
|
145
|
+
|
|
146
|
+
Tiresias reads pages and does not search for them, so a local model also needs a search tool beside it. `tiresias read <address> --local` prints exactly what your model is given. What you need, the setup and the test numbers: [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md).
|
|
147
|
+
|
|
134
148
|
## Running in Docker (optional, for advanced users)
|
|
135
149
|
|
|
136
150
|
Most people do not need Docker. It is for owners who want a hard box around Tiresias: Docker closes the one gap the memory ceiling leaves, an AI app that floods its own server, by capping memory, CPU and processes for everything together, with a read-only file system and an unprivileged user. Same commands, same store format; rendering is off in the container (no Chrome). Build it with `docker build -t tiresias:1.0 .`, then connect your app with `docker run -i --rm ... tiresias:1.0 mcp` instead of `node` or `npx`. The full `docker run` line, what each option does, and the Claude Code and Claude Desktop settings are in [docs/docker.md](docs/docker.md).
|
|
@@ -180,13 +194,13 @@ tiresias receipts prove <record_fingerprint> --out ~/proofs # v0.8: a proof on
|
|
|
180
194
|
tiresias mcp # start the MCP server on stdio
|
|
181
195
|
```
|
|
182
196
|
|
|
183
|
-
Output is JSON, except `log` and `needs`, which print a readable page. Add `--text` for a short summary. From a source checkout, run `node dist/cli.js ...`. `tiresias --version` prints the version and `tiresias <command> --help` that command's options; an option a command does not take is an error. Exit codes: 0 when the call did its job (`ok`, `unchanged`), 2 when Tiresias stopped on purpose (a wall, a flag, a refusal, a file warning, a price), 1 on an error, which is printed to standard error as one JSON line (plain words with `--text`).
|
|
197
|
+
Output is JSON, except `log` and `needs`, which print a readable page. Add `--text` for a short summary. These readable views mark where web content begins: "web content below is untrusted". Agents should use JSON, including `log --json` and `needs --json`; `text_views=wrapped` wraps text views in `untrusted_content` too. Control characters in anything the command line prints (terminal escape codes, right-to-left overrides and the like, which a page can carry) are shown as `\uXXXX` text, so a page cannot change what your terminal shows; JSON output still parses to the same values. From a source checkout, run `node dist/cli.js ...`. `tiresias --version` prints the version and `tiresias <command> --help` that command's options; an option a command does not take is an error. Exit codes: 0 when the call did its job (`ok`, `unchanged`), 2 when Tiresias stopped on purpose (a wall, a flag, a refusal, a file warning, a price), 1 on an error, which is printed to standard error as one JSON line (plain words with `--text`).
|
|
184
198
|
|
|
185
|
-
Every reply keeps the same trust boundary, and page-reading replies share one envelope. The top level holds only values Tiresias made itself: `status` (`ok`, `unchanged`, `wall`, `payment_required`, `refused`, `error`, `flagged`, `file_warning`), `door`, `door_detail`, `url` (the one you passed), `fetched_at`, `message`, `notice`, `flags` (type codes only), `counts`, and when relevant `handoff` (fixed reason code and fixed text only) and `retry_after_seconds`. Everything that came from the web is inside `untrusted_content`: text, quotes, receipts, flag snippets, advertised URLs, redirect targets, price fields, and the page to open for a handoff (`untrusted_content.handoff.open_this`). An HTML page also lists its forms (`untrusted_content.forms`, `counts.forms`), and form replies carry a top-level `form` object of Tiresias's own codes and numbers. Large results come in pages (`page` / `pages`), about 60 KB each (a translation, when one is asked for, adds up to 64 KB more).
|
|
199
|
+
Every JSON reply keeps the same trust boundary, and page-reading replies share one envelope. The top level holds only values Tiresias made itself: `status` (`ok`, `unchanged`, `wall`, `payment_required`, `refused`, `error`, `flagged`, `file_warning`), `door`, `door_detail`, `url` (the one you passed), `fetched_at`, `message`, `notice`, `flags` (type codes only), `counts`, and when relevant `handoff` (fixed reason code and fixed text only) and `retry_after_seconds`. Everything that came from the web is inside `untrusted_content`: text, quotes, receipts, flag snippets, advertised URLs, redirect targets, price fields, and the page to open for a handoff (`untrusted_content.handoff.open_this`). An HTML page also lists its forms (`untrusted_content.forms`, `counts.forms`), and form replies carry a top-level `form` object of Tiresias's own codes and numbers. Large results come in pages (`page` / `pages`), about 60 KB each (a translation, when one is asked for, adds up to 64 KB more).
|
|
186
200
|
|
|
187
201
|
## Where things are stored
|
|
188
202
|
|
|
189
|
-
`~/.tiresias/` (or `$TIRESIAS_HOME`): `cache/` (per-URL ETag, Last-Modified, content hash and parsed page), `cooldowns.jsonl` (per-site Retry-After waits, shared by every profile), `bookmarks/` (one small file per bookmark), `handoffs/` (one small file per open handoff ticket), `safety/` (the Safe Browsing list, about 11 MB, replaced once a day), `history/` and `receipts/` (one append-only file per UTC day, which also holds a record of each form sent, like `2026-10-16.jsonl`, named by the date of each record's own timestamp; the older single `history.jsonl` and `receipts.jsonl` from v0.1 are still read), optionally `config.json`, `quarantine/` (empty except for the moment your own scanner is handed a file with `--send-file`), and `slips/` (one small signed file per permission slip, plus one file per use) with its own key `keys/slips.private.jwk`, `saved/` (v0.8: the snapshots you allowed, one folder each, signed with the same slip key), `anchors/` (v0.8: one file per anchored batch: fingerprints, salts and the timestamp proof, no content or URLs; never removed by `clear`), and `profiles/<name>/`, one folder per extra profile with its own copy of this layout. Folders are owner-only (0700), files 0600, and symlinked store files and a symlinked store folder are refused. Pages that send `Cache-Control: no-store` are not cached. None of these files is sent anywhere. What leaves your machine is the requests to the sites you read (with their robots.txt and discovery files), the Safe Browsing list download from GitHub (once a day, retried after an hour when it fails), when you turn anchoring on and run `tiresias anchor`, one hash per batch to the OpenTimestamps calendars, and, only if you set up a Google Web Risk key, each URL Tiresias checks, sent to Google.
|
|
203
|
+
`~/.tiresias/` (or `$TIRESIAS_HOME`): `cache/` (per-URL ETag, Last-Modified, content hash and parsed page), `cooldowns.jsonl` (per-site Retry-After waits, shared by every profile), `bookmarks/` (one small file per bookmark), `handoffs/` (one small file per open handoff ticket), `safety/` (the Safe Browsing list, about 11 MB, replaced once a day), `history/` and `receipts/` (one append-only file per UTC day, which also holds a record of each form sent, like `2026-10-16.jsonl`, named by the date of each record's own timestamp; the older single `history.jsonl` and `receipts.jsonl` from v0.1 are still read), optionally `config.json`, `quarantine/` (empty except for the moment your own scanner is handed a file with `--send-file`), and `slips/` (one small signed file per permission slip, plus one file per use) with its own key `keys/slips.private.jwk`, `saved/` (v0.8: the snapshots you allowed, one folder each, signed with the same slip key), `anchors/` (v0.8: one file per anchored batch: fingerprints, salts and the timestamp proof, no content or URLs; never removed by `clear`), `guard/` (v1.2, only after `tiresias guard setup`: the meaning check's vectors, the texts you imported and a record of how it was built; removed by `tiresias guard off`), and `profiles/<name>/`, one folder per extra profile with its own copy of this layout. Folders are owner-only (0700), files 0600, and symlinked store files and a symlinked store folder are refused. Pages that send `Cache-Control: no-store` are not cached. None of these files is sent anywhere. What leaves your machine is the requests to the sites you read (with their robots.txt and discovery files), the Safe Browsing list download from GitHub (once a day, retried after an hour when it fails), when you turn anchoring on and run `tiresias anchor`, one hash per batch to the OpenTimestamps calendars, and, only if you set up a Google Web Risk key, each URL Tiresias checks, sent to Google. With the meaning check set up, the passages a local read is about to show go to the embedding address you gave it, usually your own computer.
|
|
190
204
|
|
|
191
205
|
## Signing your requests
|
|
192
206
|
|
|
@@ -195,12 +209,14 @@ Tiresias can sign every request it sends, so a site can check that it really cam
|
|
|
195
209
|
1. Make a key: `tiresias keys init`. It writes a private Ed25519 key to `~/.tiresias/keys/ed25519.private.jwk` (owner-only) and never prints it. It refuses to run inside a synced folder (OneDrive, iCloud Drive, Dropbox, Google Drive; judged by the real folder, not by a word in the name), because syncing would copy the private key elsewhere. It will not replace an existing key unless you add `--force`.
|
|
196
210
|
2. Run `tiresias keys show` (or `keys directory`) to get the public key and the directory JSON.
|
|
197
211
|
3. Publish that directory at `https://<your site>/.well-known/http-message-signatures-directory`. Verifiers want the directory's response signed too, and there are two ways to do it:
|
|
198
|
-
- **Signed live (what Cloudflare asks for).** A small server, such as a Cloudflare Worker, holds a copy of the private key as a secret and signs each directory response as it is served, with a short expiry. Cloudflare's bot registry asked Raibit for signatures that expire within an hour, so Raibit's own directory on raibit.ai has been signed this way since 2026-10-27 (5-minute signatures). The cost is a second copy of the key on that server: if that account is ever broken into, make a new key (`tiresias keys
|
|
212
|
+
- **Signed live (what Cloudflare asks for).** A small server, such as a Cloudflare Worker, holds a copy of the private key as a secret and signs each directory response as it is served, with a short expiry. Cloudflare's bot registry asked Raibit for signatures that expire within an hour, so Raibit's own directory on raibit.ai has been signed this way since 2026-10-27 (5-minute signatures). The cost is a second copy of the key on that server: if that account is ever broken into, make a new key (`tiresias keys rotate --overlap 0`) and publish the new directory. Tiresias does not include the server; any code that signs per RFC 9421 with the tag `http-message-signatures-directory` will do.
|
|
199
213
|
- **Pre-signed, as static files.** `tiresias keys sign-directory --out <folder> --host example.com` (`--host` may be left out once step 4 has set `signature_agent`; `--days` is 1 to 90, default 30) writes the directory body and the exact headers to serve with it (Content-Type, Signature, Signature-Input). The response is signed on your machine, so the private key never leaves it. The signature stops working on the expiry date it prints: run it again and re-upload before then. This suits a verifier that accepts day-long signatures; it does not meet Cloudflare's one-hour limit.
|
|
200
214
|
4. Put the origin of that site in `config.json` as `"signature_agent": "https://example.com"` (just the site: no path or query).
|
|
201
215
|
|
|
202
216
|
From then on every https request to a site is signed: pages, robots.txt, discovery probes and each redirect hop (for its own site). Plain http requests are never signed, and neither are Google Web Risk lookups (if you set a key). An http-only call does not load or validate the signing key: a damaged key is noticed on the next https request that needs it, or by `tiresias keys show`. Signatures last 60 seconds. If signing an https request fails (a damaged key file, a bad address), the call stops with a clear message instead of sending unsigned. Private mode still signs. Each browsing reply (read, doors, check and the others that fetch a site) that sent a request carries `"signed": true` or `false`.
|
|
203
217
|
|
|
218
|
+
To change keys, run `tiresias keys rotate`. New requests are signed with the new key at once, and the old key stays in the directory for 7 days (`--overlap` 0 to 30 days) so sites that cached it catch up; then it drops out by itself, or at once with `tiresias keys rotate --finish`. During that window `keys sign-directory` signs with both keys and its signatures end with the window, so sign again after it. After a leak use `--overlap 0`. `tiresias keys rotate --slips --confirm "YES, ROTATE THE SLIP KEY"` does the same for the permission slip key: it revokes every slip, and saved pages stay checkable. SECURITY.md has the steps for each key ("If your key leaks").
|
|
219
|
+
|
|
204
220
|
**Cloudflare.** Raibit's own copy of Tiresias is listed in Cloudflare's bot directory as an Intermediary agent (it fetches at a person's request and returns the page to that person), and Cloudflare verifies its signed requests (checked on 2026-11-01 against Cloudflare's test page, which answered "this is a verified web-bot-auth-request"). Signatures are per owner: your copy signs with your key and your `signature_agent`, so Cloudflare recognises it only once you register your own directory with Cloudflare.
|
|
205
221
|
|
|
206
222
|
`signature_agent_style` is `"quoted"` by default (the header form Cloudflare accepts today); set `"dictionary"` for the newer IETF form.
|
|
@@ -211,9 +227,9 @@ A PDF is read as text, one section per page ("Page 1", "Page 2", ...). A receipt
|
|
|
211
227
|
|
|
212
228
|
It uses Mozilla's pdf.js, locked down (these are pdf.js options Tiresias sets; the process limits are in the next paragraph): only the bytes Tiresias already fetched are used, nothing is downloaded, no script or action in the PDF runs, forms and attachments are ignored, links in a PDF are not listed or followed, and nothing is rendered. A PDF is recognised by the exact type `application/pdf` (parameters and case ignored), or by starting with `%PDF-` when the type is missing, `application/octet-stream` or `binary/octet-stream`. An explicit `text/html` or `text/plain` response is never treated as a PDF.
|
|
213
229
|
|
|
214
|
-
HTML and SVG nesting is tracked up to 256 elements; further nesting is flattened and its text is kept. List indentation stops at eight levels. Forms on a page whose nesting was flattened are listed but refused as `too_large`, since flattening can change which fields belong to a form. Parser results whose JSON is over 16,777,216 characters (UTF-16 code units) are refused as `page_too_complex` before leaving the worker.
|
|
230
|
+
HTML and SVG nesting is tracked up to 256 elements; further nesting is flattened and its text is kept. List indentation stops at eight levels. Forms on a page whose nesting was flattened are listed but refused as `too_large`, since flattening can change which fields belong to a form. Parser results whose JSON is over 16,777,216 characters (UTF-16 code units) are refused as `page_too_complex` before leaving the worker. Receipt construction is also bounded before it starts; a page with too many sections or blocks for the length of its source URL is refused as `page_too_complex`.
|
|
215
231
|
|
|
216
|
-
Each PDF is read in its own short-lived child process, not in the parser's worker thread, because pdf.js can allocate memory (decoder buffers) that a thread's heap limit does not count. The child gets an empty environment, no shell and no stdout, and runs under Node's permission model: it may read only Tiresias's own folder and the `node_modules` folder it was installed with (not your files, not `~/.tiresias` and its keys), and may start
|
|
232
|
+
Each PDF is read in its own short-lived child process, not in the parser's worker thread, because pdf.js can allocate memory (decoder buffers) that a thread's heap limit does not count. The child gets an empty environment, no shell and no stdout, and runs under Node's permission model: it may read only Tiresias's own folder and the `node_modules` folder it was installed with (not your files, not `~/.tiresias` and its keys), and may not start worker threads. Node's permission model does not limit the network: the child is simply given no address and no code that fetches. Tiresias watches the child's real memory (resident set size: `VmRSS` from `/proc/<pid>/status` on Linux, `ps -o rss=` on macOS, checked every 50 ms) and kills it with SIGKILL above 1024 MB (`TIRESIAS_PDF_MEMORY_MB`), or when the time budget runs out (5 seconds, `TIRESIAS_PARSE_BUDGET_MS`), or when the call is cancelled. A PDF that crashes, runs out of memory or is killed ends as `page_too_complex` and nothing is saved. The child dies with its parent, even if it is stuck in a loop (a separate watchdog process kills it when the parent's IPC channel closes). Starting a process costs a fraction of a second per PDF (a cold start).
|
|
217
233
|
|
|
218
234
|
**If memory cannot be watched, PDFs are not read.** Before starting a child, Tiresias checks that it can read memory use on this system. If it cannot (Windows, or no `ps` or `/proc`), a PDF answers with a clear error and web pages are unaffected. Windows therefore cannot read PDFs.
|
|
219
235
|
|
|
@@ -225,9 +241,9 @@ Limits: a PDF over the 5 MB fetch cap is refused with a message that says so (it
|
|
|
225
241
|
|
|
226
242
|
## Private mode
|
|
227
243
|
|
|
228
|
-
Add `--private` to `read`, `doors` or `check`, pass `private: true` to the MCP tools, or start a whole session with `TIRESIAS_PRIVATE=1` (for example `TIRESIAS_PRIVATE=1 tiresias mcp`). A private call
|
|
244
|
+
Add `--private` to `read`, `doors` or `check`, pass `private: true` to the MCP tools, or start a whole session with `TIRESIAS_PRIVATE=1` (for example `TIRESIAS_PRIVATE=1 tiresias mcp`). A private call keeps no page record: no history line, no receipts, and it neither reads nor writes the page cache, probe reuse or shared robots state, so it never shows or records an earlier page visit (a rendered private read still uses Chrome's throwaway profile in the system temp folder, deleted afterwards). The reply carries `"private": true`.
|
|
229
245
|
|
|
230
|
-
Private is local only, like a browser's private window. The site still sees the same honest `Tiresias` user agent, and robots.txt and Retry-After are still obeyed.
|
|
246
|
+
Private is local only, like a browser's private window. The site still sees the same honest `Tiresias` user agent, and robots.txt and Retry-After are still obeyed. Minimal politeness state is still written: origin and times for spacing across processes (private calls and form previews included), and if a site answers 429 or 503, or a redirect asks for a wait, that wait is recorded (the site's address and the deadline, never the page path), because obeying the site comes before local privacy. `private_spacing=none` disables shared spacing for private calls and previews after confirmation; Retry-After is always kept.
|
|
231
247
|
|
|
232
248
|
## Storage limits and cleanup
|
|
233
249
|
|
|
@@ -241,7 +257,7 @@ Defaults: keep history 90 days, receipts 90 days, cached pages 30 days, and brin
|
|
|
241
257
|
|
|
242
258
|
Each value must be a whole number of 1 or more; a bad limit value is reported plainly by `tiresias clear` and never breaks a read. (A `config.json` that is not valid JSON at all does stop reads, with a message saying so, because the risky settings in it cannot be judged.) Tiresias trims past-limit data by itself at most once a day, on the first normal (non-private) call. `tiresias clear` does it on demand: `--older-than 30d` (whole days) overrides the age limits for that run, `--all` removes all history, receipts and cached pages, and `--dry-run` shows what would go without changing anything. It reports what it removed and the bytes freed.
|
|
243
259
|
|
|
244
|
-
Cleanup only deletes whole files (a day of history, a day of receipts, a cached page) and never rewrites one, so it is safe beside running agents and `--dry-run` shows exactly what a real run would remove. Waits recorded in `cooldowns.jsonl` are never compacted or deleted by Tiresias, not even by `--all` (it grows
|
|
260
|
+
Cleanup only deletes whole files (a day of history, a day of receipts, a cached page) and never rewrites one, so it is safe beside running agents and `--dry-run` shows exactly what a real run would remove. Waits recorded in `cooldowns.jsonl` are never compacted or deleted by Tiresias, not even by `--all` (it grows when a site asks for a wait). Deleting it by hand is safe only when no Tiresias process is running. `clear --dry-run`, `log` and the history and receipts commands never create the store folder or change its permissions.
|
|
245
261
|
|
|
246
262
|
## What changed, needs and bookmarks
|
|
247
263
|
|
|
@@ -249,7 +265,7 @@ Cleanup only deletes whole files (a day of history, a day of receipts, a cached
|
|
|
249
265
|
|
|
250
266
|
**Needs report (W-12).** `tiresias needs` (MCP `needs_report`) reads the last 30 days of history (`--since` to change it) and lists the walls hit by site and reason, questions that came back empty, reads where the site offered a better door, pages read most often, and sites visited 3 or more times that offer no agent door. Each pattern comes with a suggested want or need for you to accept or reject. It is built when you ask and never stored.
|
|
251
267
|
|
|
252
|
-
**Bookmarks and watchlist (W-16).** `tiresias bookmark add <name> <url> [--watch]`, `bookmark remove <name>`, `bookmark watch <name> on|off`, `bookmark list`. Names are 1 to 64 characters of `a-z`, `0-9` and `-`; at most 1,000 bookmarks, one small file each in `~/.tiresias/bookmarks/`. `tiresias watch` checks every watched bookmark like a normal `check` (robots.txt, waits and signing all apply), and reports the ones that changed, with what changed. It also names the bookmarks that were walled, failed or are waiting on a site's Retry-After (in `attention`: name, outcome, the wall reason or the seconds to wait; their URLs are inside `untrusted_content`), at most 100, since those are the ones a person may need to act on. Unchanged ones are only counted. A changed bookmark shows the start of its list of changes; for all of it, run `tiresias check <url>` from page 1. `watch --text` (the form the cron line below uses) prints the changed bookmarks with their counts and the ones needing attention with the reason, so the log says what to look at. Tiresias has no scheduler; run it yourself, for example with cron (`crontab -e` on macOS or Linux):
|
|
268
|
+
**Bookmarks and watchlist (W-16).** `tiresias bookmark add <name> <url> [--watch]`, `bookmark remove <name>`, `bookmark watch <name> on|off`, `bookmark list`. Names are 1 to 64 characters of `a-z`, `0-9` and `-`; at most 1,000 bookmarks, one small file each in `~/.tiresias/bookmarks/`. `tiresias watch` checks every watched bookmark like a normal `check` (robots.txt, waits and signing all apply), and reports the ones that changed, with what changed. It also names the bookmarks that were walled, failed or are waiting on a site's Retry-After (in `untrusted_content.attention`: name, outcome, the wall reason or the seconds to wait; their URLs are also inside `untrusted_content`), at most 100, since those are the ones a person may need to act on. Unchanged ones are only counted. A changed bookmark shows the start of its list of changes; for all of it, run `tiresias check <url>` from page 1. `watch --text` (the form the cron line below uses) prints the changed bookmarks with their counts and the ones needing attention with the reason, so the log says what to look at. Tiresias has no scheduler; run it yourself, for example with cron (`crontab -e` on macOS or Linux):
|
|
253
269
|
|
|
254
270
|
```
|
|
255
271
|
0 7 * * * /full/path/to/tiresias watch --text >> ~/tiresias-watch.log 2>&1
|
|
@@ -262,7 +278,7 @@ Bookmarks are your saved list, not browsing data: `clear` (even `--all`) never r
|
|
|
262
278
|
**Handoff and resume (W-06).** When a read stops at a wall (a bot check, a CAPTCHA, a login, a 403), the reply carries `handoff.ticket`, an id for picking up later, next to the page for a person to open (`untrusted_content.handoff.open_this`). The person opens it and gets through themselves. Then either:
|
|
263
279
|
|
|
264
280
|
- `tiresias resume <ticket>` (MCP `resume` with `ticket`) runs the same read again, with the same question and section. robots.txt, waits, signing and wall detection all apply, and it always asks the site. If the wall is still there, you get it back with the same ticket.
|
|
265
|
-
- `tiresias resume <ticket> --from-file <saved page>`
|
|
281
|
+
- `tiresias resume <ticket> --from-file <saved page>` reads the page the person saved (HTML, markdown, text, or PDF from a file; at most 5 MB). Tiresias sends nothing to the site for it, so no cookies or logins are ever involved. The reply and every receipt say `source: "provided_by_person"`, and the page is not cached, because it may show the person's own logged-in view. MCP `resume` with `text` is recorded as `provided_by_agent` in the reply, receipts and history: Tiresias cannot verify that a person supplied it.
|
|
266
282
|
|
|
267
283
|
A ticket is removed once the read succeeds and expires after 7 days (`keep_handoff_days`). `tiresias handoffs` lists the open ones. At most 500 are kept. Private mode keeps no ticket and says so. Only `read` keeps tickets; `watch` names walled bookmarks instead.
|
|
268
284
|
|
|
@@ -312,7 +328,7 @@ tiresias profile remove client-a --yes # add --delete-key if it has a sig
|
|
|
312
328
|
- Without `--profile`, Tiresias uses the `default` profile, which is the store folder itself, exactly as before. Existing stores need no change.
|
|
313
329
|
- Other profiles live in `~/.tiresias/profiles/<name>/`. A profile that does not exist is an error: using it never creates it.
|
|
314
330
|
- The MCP server serves one profile, chosen when it starts. An agent cannot switch profiles in the middle of a session, and every reply names the profile (`"profile": "client-a"`) when it is not `default`.
|
|
315
|
-
- Three things are shared by every profile, at the store root: Retry-After waits (`cooldowns.jsonl`; a site that asked us to wait is obeyed whatever the profile), the Safe Browsing list (`safety/`, public data), and the per-site spacing slots (`hosts/`: a fingerprint of each site's origin, the time of its last request and short-lived lease files, so every process keeps
|
|
331
|
+
- Three things are shared by every profile, at the store root: Retry-After waits (`cooldowns.jsonl`; a site that asked us to wait is obeyed whatever the profile), the Safe Browsing list (`safety/`, public data), and the per-site spacing slots (`hosts/`: a fingerprint of each site's origin, the time of its last request and short-lived lease files, so every process keeps at least a second between requests, apart from the first page of a visit right after robots.txt; old entries are removed by the daily trim).
|
|
316
332
|
- `clear`, the daily trim and the disk cap work on one profile at a time. `clear --all` on `default` never touches other profiles or the shared files.
|
|
317
333
|
- The Web Risk key file `~/.config/tiresias/secrets.env` belongs to `default`. Another profile uses Web Risk only when its own `config.json` names a key file (or `TIRESIAS_WEB_RISK_KEY` is set for that process).
|
|
318
334
|
- `profile remove` deletes only that profile's folder, after checking that everything in it is a plain file or folder you own (a link stops it before anything is deleted). It first renames the folder away in one step, so the profile disappears for every running process at once; a process still serving it then gets an error instead of recreating it. A deleted signing key cannot be recovered, so it needs `--delete-key` as well as `--yes`.
|
|
@@ -344,15 +360,15 @@ A form is an action taken in your name, so Tiresias shows it, previews it, and s
|
|
|
344
360
|
tiresias slip grant --action submit_form --site https://example.com --path /contact --uses 1 --note "the contact form"
|
|
345
361
|
```
|
|
346
362
|
|
|
347
|
-
**2. Your agent reads the page and sees its forms.** `read` lists them inside `untrusted_content.forms`: each form's number, method, where it sends, and its fields with their labels, defaults and choices. Fields the site fills in itself (hidden fields, often a security token) are listed by name only, as `set by the site`; their values are never shown to the agent. Forms with a password, a file upload, card or bank fields (hidden ones too), or a CAPTCHA are marked `not_allowed` and are never sent: a person handles those. So are GET forms with hidden fields (their values would land in the address), forms that send to an address whose path is not plain (only letters, digits, `_`, `~`, `-` and single dots between them; some real sites' addresses fail this and cannot be submitted to), forms with a field name that is not plain or two fields whose names a server could treat as one (`role_flag` and `role.flag`), POST forms with no address of their own on a page whose address has a query, forms whose hidden values are not plain printable ASCII (a space, line break or accented letter), and any request that would carry a card number anywhere, whoever typed it.
|
|
363
|
+
**2. Your agent reads the page and sees its forms.** `read` lists them inside `untrusted_content.forms`: each form's number, method, where it sends, and its fields with their labels, defaults and choices. Fields the site fills in itself (hidden fields, often a security token) are listed by name only, as `set by the site`; their values are never shown to the agent. Forms with sign-in actions or username autocomplete, a password, a file upload, payment or purchase actions (including saved funds), card or bank fields (hidden ones too), or a CAPTCHA are marked `not_allowed` and are never sent: a person handles those. (Sign-in, payment and purchase actions are recognized from word lists in 13 languages, so a form worded another way can go unmarked; the slip, not the word list, is the guarantee. See SECURITY.md.) So are GET forms with hidden fields (their values would land in the address), forms that send to an address whose path is not plain (only letters, digits, `_`, `~`, `-` and single dots between them; some real sites' addresses fail this and cannot be submitted to), forms with a field name that is not plain or two fields whose names a server could treat as one (`role_flag` and `role.flag`), POST forms with no address of their own on a page whose address has a query, forms whose hidden values are not plain printable ASCII (a space, line break or accented letter), and any request that would carry a card number anywhere, whoever typed it.
|
|
348
364
|
|
|
349
|
-
**3. The agent previews** (`form_preview`, or `tiresias form preview <url> --form 1 --set name=Ann --set email=ann@example.com`; `--set` repeated with one name gives a checkbox group or multiple select several values, and `--unset name` chooses none). Tiresias fetches the page fresh, checks the values against the form (known fields only, listed choices only, required fields filled, lengths respected) and shows the exact request it would send: method, full address, and the encoded body, with each hidden value shown as `[set by the site]`. It also says whether a slip covers that address and gives a `preview_hash`.
|
|
365
|
+
**3. The agent previews** (`form_preview`, or `tiresias form preview <url> --form 1 --set name=Ann --set email=ann@example.com`; `--set` repeated with one name gives a checkbox group or multiple select several values, and `--unset name` chooses none). Tiresias fetches the page fresh, checks the values against the form (known fields only, listed choices only, required fields filled, lengths respected) and shows the exact request it would send: method, full address, and the encoded body, with each hidden value shown as `[set by the site]`. It also says whether a slip covers that address and gives a `preview_hash`. The previewed form is not sent. Only Retry-After and minimal spacing state are saved by default. With `get_form_actions=slip`, fetching a page at a known GET form action also needs and spends a slip use.
|
|
350
366
|
|
|
351
367
|
**4. The agent submits** (`form_submit` with the same values and the `preview_hash`, or `tiresias form submit ... --preview <hash>`). In that one call Tiresias fetches the page again and rebuilds the request. If the form or the values changed since the preview, it refuses (`form_changed`) and sends nothing. It checks the address the form sends to (Safe Browsing, with no way to override a flag; robots.txt; any wait the site asked for), and only then uses one use of your slip. No slip, no request. The form is sent once and never retried, with the site's own hidden values from this fetch and only the cookies the site set during this call (kept in memory, thrown away afterwards, never sent to another site). No redirect after a submit is followed, so the form can never be sent twice; the reply gives the address the site pointed to, which the agent can read with `read`. The reply has the HTTP status, which slip use was spent, and the answer page read like any page.
|
|
352
368
|
|
|
353
|
-
If the site's answer repeats one of its hidden values, or a cookie it set while the form was fetched (of 6 characters or more), Tiresias withholds the whole answer (since v0.9): the reply says the form was sent and gives the HTTP status and size, with `form.reason: "secret_withheld"`, and nothing from the answer is shown or recorded. The answer is checked
|
|
369
|
+
If the site's answer repeats one of its hidden values, or a cookie it set while the form was fetched (of 6 characters or more), Tiresias withholds the whole answer (since v0.9): the reply says the form was sent and gives the HTTP status and size, with `form.reason: "secret_withheld"`, and nothing from the answer is shown or recorded. The answer is checked as received, and its extracted text is checked again before anything is shown or recorded, with HTML, percent and JSON escapes decoded and case, quotes and spaces ignored, so the usual spellings of an echo are all caught; an echo in an encoding Tiresias does not decode (base64, a hash) is not. It is the site's own secret from this one call, so this is best effort: Tiresias tries not to see it. Shorter values are not checked: every `1` or `en` in a page would match, and a value that short is not a secret.
|
|
354
370
|
|
|
355
|
-
The guard that refuses login, password, CAPTCHA and payment forms errs toward refusing: a form is refused (`not_allowed`) when a marker word appears anywhere in its fields, labels or surrounding text, even run together with other words, so
|
|
371
|
+
The guard that refuses login, password, CAPTCHA and payment forms errs toward refusing: a form is refused (`not_allowed`) when a marker word appears anywhere in its fields, labels or surrounding text, so an ordinary form is sometimes refused too. Markers such as `password` and `captcha` count even when run together with other words; action words such as "buy", "pay" and "sign in" count only as whole words, so "Buyers" does not refuse a form. `not_allowed` means "an agent should not send this", not proof of what the form does. What Tiresias promises, and what stays the site's own job (how its server reads parameters), is written down in docs/SPEC.md section 9 ("What form submission guarantees").
|
|
356
372
|
|
|
357
373
|
What is kept: a history line for each submit, and in the receipts log a record of what was sent (where, which slip, the field names and the values from visible fields, each value cut at 2,000 characters and the record marked `cut: true` when it had to be shortened; hidden fields by name only). Private mode refuses `form_submit` (using a slip writes), and preview works privately. GET forms (like a search box) need a slip too: every form is an action.
|
|
358
374
|
|
|
@@ -363,7 +379,7 @@ When a link leads to a file instead of a page, Tiresias decides what it is from
|
|
|
363
379
|
- **What the warning says** (top-level `file_warning`): `kind` (`program`, `script`, `shortcut`, `addon`, `archive`, `office`, `image`, `media` or `unknown`), `risk` (`low` for images and media, `high` for everything else, unknown files included), `size`, a `fingerprint` (`sha256:...`), `flags` and a fixed `reason`. The URL, final URL and the declared type and name are inside `untrusted_content`. A file is hashed as it streams and never held whole (except a body sent with `Content-Encoding: deflate`, collected compressed up to the cap to inflate it safely, and a zip or Office file Tiresias looks inside, held in memory up to 20 MiB, `TIRESIAS_MAX_INSPECT_BYTES`); over `TIRESIAS_MAX_FILE_BYTES` (default 50 MB) the download stops and the warning has no fingerprint, and a file the site says is bigger than that is not downloaded at all.
|
|
364
380
|
- **Flags:** `type_mismatch` when the declared type or name disagrees with the content (an "invoice.pdf" that is a program), `double_extension` for names like `invoice.pdf.exe`.
|
|
365
381
|
- **Text kinds** are read, never run, and flagged: scripts (`.sh`, `.js`, `.ps1`, a `#!` first line and the like) as plain text with the `script` flag; SVG images as text only (scripts and styles dropped, the injection shield on) with `svg`; CSV with `csv_formulas` and a count when cells start like a spreadsheet formula; calendar (`.ics`) and contact (`.vcf`) files with `calendar` or `contact`, their links listed and never followed. Shortcut and system files served as text (`.url`, `.desktop`, `.reg`, `.mobileconfig`, `.inf`, `.library-ms`) are never read: they are file warnings. PDFs keep their text and add `pdf_javascript`, `pdf_attachments` or `pdf_launch` when they hold those (none of them is run or opened; `pdf_launch` is looked for in the file's plain bytes, so one inside a compressed object stream is not seen).
|
|
366
|
-
- File warnings are recorded in history and receipts (never in private mode), counted by the daily log and the needs report, and named under `attention` by `watch`. They work the same from `check`, `watch`, `resume` (including a file a person saved) and a form's answer.
|
|
382
|
+
- File warnings are recorded in history and receipts (never in private mode), counted by the daily log and the needs report, and named under `untrusted_content.attention` by `watch`. They work the same from `check`, `watch`, `resume` (including a file a person saved) and a form's answer.
|
|
367
383
|
|
|
368
384
|
**Your own scanner (optional).** Tiresias does no virus checking of its own and calls no outside service. If you already use one, you can connect it, and every high-risk file warning that was downloaded whole (so it has a fingerprint) is checked automatically; a file over the size cap, stopped by time, or not downloaded at all is not:
|
|
369
385
|
|
|
@@ -387,14 +403,37 @@ Every successful read (`ok` or `unchanged`, not private) opens a numbered tab. `
|
|
|
387
403
|
|
|
388
404
|
`tiresias settings` is the settings page: every owner setting with its current value, its default, a line on what it does and where it is stored (`config.json` in the profile's folder, or an environment variable). `tiresias settings set <name> [<site>] <value>` changes one and `tiresias settings reset <name> [<site>]` puts back the default; every value is checked before the file is written, the file is written whole or not at all, and a bad `config.json` is reported by the name of the key that is wrong. Only the command line can do this: no MCP tool reads or changes a setting.
|
|
389
405
|
|
|
390
|
-
**Risky settings need confirmation (v0.9, W-32).** An agent that can run commands on your computer can run `tiresias settings` too, so turning a risky setting on or looser takes an exact all-caps phrase naming it, given as `--confirm`: `tiresias settings set saving ask --confirm "YES, TURN ON SAVING"`. Without it, or with any other text, nothing changes and the reply prints the exact phrase. Turning a setting off or stricter never asks. Risky: `saving`, `rendering` (`ask`, and `auto` with its own phrase), `translator`, `scanner` with `--send-file`, `anchoring`, `anchor_calendars` (adding one), `safe_browsing` off, and per site more `ports`, lower `spacing_seconds`, and `never_visit` or `hand_off` turned off. An agent may type the phrase; the point is that nothing is loosened by accident or in passing, and every change made with a settings command is written to `tiresias history` and the daily log with who made it (whether the command ran at a terminal, so likely you, or not, so an agent, a script or cron: a best guess), and every reply, CLI and MCP, carries a short `settings_notice` for 24 hours. It does not stop an agent that is fully fooled into typing the phrase; the log and the notice make that visible.
|
|
406
|
+
**Risky settings need confirmation (v0.9, W-32).** An agent that can run commands on your computer can run `tiresias settings` too, so turning a risky setting on or looser takes an exact all-caps phrase naming it, given as `--confirm`: `tiresias settings set saving ask --confirm "YES, TURN ON SAVING"`. Without it, or with any other text, nothing changes and the reply prints the exact phrase. Turning a setting off or stricter never asks. Risky: `saving`, `rendering` (`ask`, and `auto` with its own phrase), `translator`, `scanner` with `--send-file`, `anchoring`, `anchor_calendars` (adding one), `safe_browsing` off, and per site more `ports`, lower `spacing_seconds`, and `never_visit` or `hand_off` turned off, plus `private_spacing none` and `hook_secrets inherit` (below). An agent may type the phrase; the point is that nothing is loosened by accident or in passing, and every change made with a settings command is written to `tiresias history` and the daily log with who made it (whether the command ran at a terminal, so likely you, or not, so an agent, a script or cron: a best guess), and every reply, CLI and MCP, carries a short `settings_notice` for 24 hours. It does not stop an agent that is fully fooled into typing the phrase; the log and the notice make that visible.
|
|
391
407
|
|
|
392
408
|
- **Editing `config.json` by hand.** Tiresias keeps the last confirmed state in `confirmations.json` next to it. A hand edit that loosens a risky setting is not in force until you confirm it (`tiresias settings confirm saving --confirm "YES, TURN ON SAVING"`); until then the confirmed value applies, and replies and `tiresias settings` say so. A hand edit that tightens applies at once. No record (a new store, or an upgrade from v0.8) means the safe defaults are the confirmed ones: confirm once what you had turned on. **Upgrading from v0.8:** if you had turned on saving, rendering or anchoring, they are held off until you confirm each one; the first reply after the upgrade lists them with the exact command, for example `tiresias settings confirm saving --confirm "YES, TURN ON SAVING"` (and the same with `rendering` and `"YES, TURN ON RENDERING"`, or `anchoring` and `"YES, TURN ON ANCHORING"`). `tiresias settings` shows what is waiting. Since v0.9.1, `tiresias mcp` also prints one line on standard error when it starts while a setting is held back, naming the exact command for each (your AI app usually keeps that in its MCP server log), so an owner who uses Tiresias only through an agent can find it too. The record is a plain file, so anything that can write to your folder can edit both; it catches accidents and casual tricks, not a determined program.
|
|
393
409
|
- **Environment variables** that loosen (`TIRESIAS_RENDERING`, `TIRESIAS_SAFE_BROWSING=0`, `TIRESIAS_ALLOW_PORTS`) apply only with their phrase in `TIRESIAS_CONFIRM` (several separated by `;`), for example `TIRESIAS_CONFIRM="YES, TURN OFF SAFE BROWSING"`; otherwise they are ignored and replies say so.
|
|
394
410
|
- **Never ask again.** `tiresias settings confirmations off --confirm "YES, NEVER ASK AGAIN FOR RISKY SETTINGS"` stops the asking (changes made with settings commands are still recorded and shown; hand edits and environment variables then apply silently); `tiresias settings confirmations on --confirm "YES, ASK AGAIN FOR RISKY SETTINGS"` turns it back on and takes what `config.json` holds then as confirmed. `tiresias settings` shows which is on, what each risky setting holds and whether it is confirmed.
|
|
395
411
|
|
|
396
412
|
- **Fast first read (`doors`).** A first read of a site returns the page right after robots.txt, in about a second instead of about seven. The checks for better doors (llms.txt, MCP, API specs) run afterwards in the background, one at a time and still spaced, and the reply says `doors_pending`; the next read uses their answers. The CLI waits for them before it exits (Ctrl-C cancels them cleanly). A private read checks them in the call, as before. `tiresias settings set doors wait` makes every first read wait for them.
|
|
397
|
-
- **Site settings (`sites`).** Per host (`example.com`) or a host and everything under it (`*.example.com`): `spacing_seconds` (1 to 30, only ever raises the
|
|
413
|
+
- **Site settings (`sites`).** Per host (`example.com`) or a host and everything under it (`*.example.com`): `spacing_seconds` (1 to 30, only ever raises the default spacing of one second; a site with this setting waits its full spacing between robots.txt and the first page too), `ports` (extra ports for that site, like `8443,9000-9100`), `hand_off` (never read it: the agent gets the link to give you, status `wall`, reason `owner_hand_off`) and `never_visit` (send it nothing, status `refused`). They apply to every request to a site, redirects and robots.txt included (Google Web Risk lookups are not spaced), and a reply names the ones that applied in `site_settings`.
|
|
414
|
+
|
|
415
|
+
The v1.1 choices are settings too, changed only through the command line or `config.json`:
|
|
416
|
+
|
|
417
|
+
| Setting | Default | Other choice |
|
|
418
|
+
|---|---|---|
|
|
419
|
+
| `get_form_actions` | `read`: links are ordinary reads | `slip`: reading a known GET form action requires and spends a `submit_form` slip |
|
|
420
|
+
| `private_spacing` | `shared`: private calls and previews share minimal spacing state | `none`: write no spacing state for them; separate processes are not spaced against each other |
|
|
421
|
+
| `hook_secrets` | `hidden`: hooks do not receive Tiresias secret variables | `inherit`: hooks receive the full environment |
|
|
422
|
+
| `text_views` | `marked`: readable text with an untrusted-content marker | `wrapped`: text inside `untrusted_content`, like JSON |
|
|
423
|
+
|
|
424
|
+
The GET action guard remembers 4,096 distinct targets exactly. Further targets seen in ordinary reads or previews stay guarded until restart, even if their saved records are cleared. At high volume, this can also make unrelated addresses need a slip. A private call keeps its own observations only until the call ends; more than 4,096 distinct private targets makes every GET in that call need a slip. After restart, only saved records that still exist are remembered.
|
|
425
|
+
|
|
426
|
+
Set them with `tiresias settings set <name> <value>`; `tiresias settings` shows their defaults and current values.
|
|
427
|
+
The two loosenings need `--confirm "YES, TURN OFF PRIVATE SPACING"` for `private_spacing none`, or
|
|
428
|
+
`--confirm "YES, SHARE TIRESIAS SECRETS WITH HOOKS"` for `hook_secrets inherit`. Like other risky settings,
|
|
429
|
+
they are held back when unconfirmed, logged with who changed them, and shown in replies.
|
|
430
|
+
|
|
431
|
+
Permission slips gate sending forms. Reading a link is a read; a site that changes something on a plain GET breaks
|
|
432
|
+
HTTP's rule that GET is safe. The `slip` setting tightens reads of GET form targets Tiresias has observed, matching
|
|
433
|
+
origin and path regardless of query. Cacheable non-private pages keep that policy in the cache; private calls and previews
|
|
434
|
+
keep observations only in memory. A gated read spends a slip use, even when reached during a form preview; private
|
|
435
|
+
calls cannot spend a slip. A claimed submission is checked again after its queue wait, right before dispatch;
|
|
436
|
+
a reserved use stays spent if it expires or is revoked while waiting.
|
|
398
437
|
|
|
399
438
|
**Inside files (v0.6).** A zip or an Office file (`.docx`, `.xlsx`, `.pptx` and their macro types) of up to `TIRESIAS_MAX_INSPECT_BYTES` (default 20 MiB) is held in memory, never on disk, and looked inside without unpacking it: a zip gives its names and declared sizes, with programs, scripts, shortcuts, nested archives, names that climb out of their folder, password-protected entries and signs of a zip bomb flagged (`file_warning.inside`, names in `untrusted_content.inside`); an Office file gives its text only, with a `macros` flag (never run) and its outside links listed (never fetched). It is still a `file_warning`: the file was never opened. A calendar file (`.ics`) also gives its events (`untrusted_content.events`: summary, start, end, organizer, location, description, URL and links), with no link followed. Looking inside is bounded, and says so when it stops short: at most 10,000 zip entries listed, 500 Office parts and 200,000 characters of Office text read, 50 calendar events kept (the rest counted).
|
|
400
439
|
|
|
@@ -410,7 +449,7 @@ tiresias translator show
|
|
|
410
449
|
tiresias translator off
|
|
411
450
|
```
|
|
412
451
|
|
|
413
|
-
It is run only when a read asks for a translation (`read --translate en`, MCP `read` with `translate: "en"`), directly (no shell, a full path), as `your-translate [args...] <source> <target>`, with the text the reply shows on standard input (at most 32 KB) and at most 64 KB of its output kept. The output goes inside `untrusted_content.translation` with a note that it is a machine translation by your tool and not the page's own words; receipts always quote the original text, and the translation is never cached or logged. If it times out, fails, prints too much or nothing, the page comes back as usual and `translation: { status, reason }` says why. It is set only from the command line or by editing `config.json` (`"translator": {"command": [...], "timeout_seconds": 20}`), and since v0.9 setting a program takes `--confirm "YES, TURN ON THE TRANSLATOR"` (see Settings); over MCP an agent can only ask for a language, never choose or change the program. It runs on macOS and Linux only, like the scanner. Both are your own programs and are trusted like you: they run with your user's rights and Tiresias
|
|
452
|
+
It is run only when a read asks for a translation (`read --translate en`, MCP `read` with `translate: "en"`), directly (no shell, a full path), as `your-translate [args...] <source> <target>`, with the text the reply shows on standard input (at most 32 KB) and at most 64 KB of its output kept. The output goes inside `untrusted_content.translation` with a note that it is a machine translation by your tool and not the page's own words; receipts always quote the original text, and the translation is never cached or logged. Successful translations are scanned for instructions aimed at an AI; the reply carries only fixed flag codes at the top level, with snippets labelled `machine translation` inside `untrusted_content.flag_details`. These findings stay specific to the reply. If the translation is dropped for size, its flag stays and its detail says the translation was omitted. If it times out, fails, prints too much or nothing, the page comes back as usual and `translation: { status, reason }` says why. It is set only from the command line or by editing `config.json` (`"translator": {"command": [...], "timeout_seconds": 20}`), and since v0.9 setting a program takes `--confirm "YES, TURN ON THE TRANSLATOR"` (see Settings); over MCP an agent can only ask for a language, never choose or change the program. It runs on macOS and Linux only, like the scanner. Both are your own programs and are trusted like you: they run with your user's rights and environment, with Tiresias secret variables removed by default (`hook_secrets=hidden`), and Tiresias's privacy and file protections do not apply to what they do (a translator also runs on private reads, since it only sees the reply's text).
|
|
414
453
|
|
|
415
454
|
## JavaScript-only pages (v0.7)
|
|
416
455
|
|
|
@@ -427,9 +466,9 @@ tiresias settings set rendering off # the default: never
|
|
|
427
466
|
It uses the **Google Chrome already installed** on your machine, driven directly over a private pipe (no extra package, and Tiresias never downloads a browser). If Chrome is not found, the read comes back as usual with `render: { status: "unavailable" }` and how to enable it (install Google Chrome, or set `TIRESIAS_CHROME` to its program path).
|
|
428
467
|
|
|
429
468
|
The page's JavaScript is treated as hostile:
|
|
430
|
-
- **Every request the page makes goes through Tiresias's own rules**, exactly like a plain read: Safe Browsing, your site settings, the private-address block, ports, robots.txt, the site's waits and spacing, and signing. Chrome's own network never reaches a site; anything that tries another way (WebSocket, WebRTC) hits a dead end Tiresias sets up. Only scripts, style sheets and data requests are fetched, and only with GET; images, fonts, media, frames, files, popups, workers, form posts and the page moving itself elsewhere are refused and counted.
|
|
469
|
+
- **Every request the page makes goes through Tiresias's own rules**, exactly like a plain read: Safe Browsing, your site settings, the private-address block, ports, robots.txt, the site's waits and spacing, and signing. Chrome's own network never reaches a site; anything that tries another way (WebSocket, WebRTC) hits a dead end Tiresias sets up. Only scripts, style sheets and data requests are fetched, and only with GET; images, fonts, media, frames, files, popups, workers, form posts, requests matching GET form actions on the page, and the page moving itself elsewhere are refused and counted. The action checks cover up to 1,000 forms and `formaction` attributes together in both the original HTML and the live page, separately from the 20 forms listed in a read. Every `formaction` attribute anywhere on the page counts as a GET address, whatever the element or its method. Any `formmethod` attribute other than post or dialog makes every form action count, including POST and dialog forms; without one, those forms stay skipped. Values are compared without trimming and without regard to case. Each scan allows 65,536 characters of action addresses in total, counting repeated addresses, with at most 2,048 characters per action in the HTML and 8,192 in the live page. The HTML scan resolves raw actions against the page URL and every distinct web base anywhere in the parsed HTML, including templates and later bases, and guards their union. Non-web bases are ignored; more than 16 distinct web bases makes the scan incomplete. Every resolution counts toward the budget, including skipped non-web results. Beyond these limits, or when a scan is incomplete or an action cannot be read safely, every subrequest is refused. Valid actions such as `javascript:void(0)` or `mailto:` are skipped because they are not web requests. Unknown form methods count as GET for this check. A literal NUL in an action, `formaction` or base href makes the HTML scan incomplete; a zero character reference becomes U+FFFD and is checked normally. The live check uses native prototype selectors, collection accessors and form, button and input getters in an isolated world. The page still controls the shared DOM, so this is a check of observed addresses, with parser differences and changes between checks as limits.
|
|
431
470
|
- Chrome's own sandbox stays on. Each render gets a new, empty browser profile that is deleted afterwards, with no cookies, no downloads, no service workers, popups closed and dialogs dismissed. Tiresias never clicks, types or submits.
|
|
432
|
-
- Hard limits: 20 seconds, 100 requests, 10 MB fetched, a rendered page of 50,000 elements and 5 MB. The browser is killed at the end of every render, whatever happened.
|
|
471
|
+
- Hard limits: 20 seconds, 100 requests, 10 MB fetched, a rendered page of 50,000 elements and 5 MB. Paused requests keep only bounded metadata; page headers and bodies are discarded, apart from the small fields needed to answer a CORS preflight. Outstanding paused requests are capped too. The browser is killed at the end of every render, whatever happened.
|
|
433
472
|
|
|
434
473
|
The rendered page then goes through the same reader and shield as any page (receipts, flags, paging, walls, language).
|
|
435
474
|
|
|
@@ -462,7 +501,7 @@ Prove later that a receipt existed at a given time and has not been edited since
|
|
|
462
501
|
```
|
|
463
502
|
tiresias settings set anchoring on --confirm "YES, TURN ON ANCHORING" # CLI or config.json, confirmed; never over MCP
|
|
464
503
|
tiresias anchor # one batch of everything new; run it by hand or from cron
|
|
465
|
-
tiresias anchor status # the batches: pending, or
|
|
504
|
+
tiresias anchor status # the batches: pending, or the Bitcoin block a calendar reported
|
|
466
505
|
tiresias anchor upgrade # ask the calendars whether pending batches reached a block
|
|
467
506
|
tiresias receipts # each record shows its record_fingerprint
|
|
468
507
|
tiresias receipts prove <record_fingerprint> --out <folder> # the proof bundle, the record and a standard .ots file
|
|
@@ -470,7 +509,7 @@ tiresias receipts verify <bundle> # check a bundle offline
|
|
|
470
509
|
```
|
|
471
510
|
|
|
472
511
|
- **Only fingerprints leave your machine, and only one per batch.** `anchor` takes the SHA-256 fingerprint of every new receipt record and saved snapshot, adds a random 32-byte salt to each, puts them in a random order and builds a Merkle tree. Only the tree's root is sent to the calendars. They learn that hash, the time, and your IP address (and your signing domain if you sign requests); never a quote, a URL or a fingerprint. The calendars are services you chose, not sites Tiresias reads: they are called directly (address, port and `never_visit` checks, a timeout and a size cap, no redirects, Retry-After cooldowns honored and recorded on 429/503), without a robots.txt or Safe Browsing check. The salt means nobody can confirm a guessed receipt from the public record, and a proof for one receipt says nothing about the others.
|
|
473
|
-
- **Proofs.** `receipts prove` writes the record, its salt, its path to the root and a `.ots` file whose digest is the record's fingerprint, so the official tool can check it too: `ots verify receipt-<id>.json.ots`. `receipts verify` checks everything it can offline and says plainly what needs the outside world: a Bitcoin block header (it gives the block height and the Merkle root to compare). It never says "proven" on its own (anyone can make a bundle that passes the offline checks): `offline_ok`, `proven: false`, exit 2; the header step decides. A failed offline check exits 1 and prints `status: "error"`, `reason: "verification_failed"` as one JSON line on standard error, with the check results; `--text` prints the failure there in plain words. A batch is pending for a few hours until a calendar puts it in a block; `anchor upgrade` (or the next `anchor`) fetches that.
|
|
512
|
+
- **Proofs.** `receipts prove` writes the record, its salt, its path to the root and a `.ots` file whose digest is the record's fingerprint, so the official tool can check it too: `ots verify receipt-<id>.json.ots`. `receipts verify` checks everything it can offline and says plainly what needs the outside world: a Bitcoin block header (it gives the block height and the Merkle root to compare). It never says "proven" on its own (anyone can make a bundle that passes the offline checks): `offline_ok`, `proven: false`, exit 2; the header step decides. A failed offline check exits 1 and prints `status: "error"`, `reason: "verification_failed"` as one JSON line on standard error, with the check results; `--text` prints the failure there in plain words. A batch is pending for a few hours until a calendar puts it in a block; `anchor upgrade` (or the next `anchor`) fetches that. Tiresias does not check a calendar's report against Bitcoin itself, so it says the batch was reported in a block by a calendar, and for 14 days it keeps asking the listed calendars that have not answered yet.
|
|
474
513
|
- **Large stores.** Every kept batch remains searchable. Receipt scans and upgrade requests are bounded per run and resume from a saved continuation in this profile’s `anchors/` folder. Replies say when a scan is incomplete and counts cover only the part scanned; run `anchor` or `anchor upgrade` again to continue. A malformed or excessive calendar addition is dropped while earlier usable proofs are kept. A failed `receipts prove --out` export removes the files created by that attempt, so a collision can be cleared and retried.
|
|
475
514
|
- **Never:** private mode (it records nothing, and `anchor` refuses in a private session); anything over MCP; a background process. A failing calendar never fails a read: anchoring only runs when you run it. Each profile anchors its own receipts into its own `anchors/` folder. Calendars: `anchor_calendars` (default: the four public OpenTimestamps calendars).
|
|
476
515
|
- **From cron** (`crontab -e`, one line; add `--profile <name>` for another profile): `17 3 * * * /full/path/to/tiresias anchor --text >> ~/.tiresias/anchor-cron.log 2>&1`
|
|
@@ -478,15 +517,15 @@ tiresias receipts verify <bundle> # check a bundle offline
|
|
|
478
517
|
## How fetching is kept safe
|
|
479
518
|
|
|
480
519
|
- Refuses non-http(s) URLs and private, loopback, link-local, CGNAT and internal addresses. IPv6 is allowed only for global unicast (and IPv4-mapped or well-known NAT64 addresses whose IPv4 address is itself allowed). The connection uses the same validated DNS answer that was checked (no second lookup), and redirects (301, 302, 303, 307 and 308 only) are followed by hand with every hop re-checked (max 5), and an https page that redirects to plain http is refused. Only ports 80, 443 and 8000 to 8999 are called (`TIRESIAS_ALLOW_PORTS` adds more). A 15 second timer covers what the site does (DNS, connection, answer, body); waits the site asked for run on the call's own 60 second deadline. 5 MB cap on decoded bytes. Since v0.7 every request is also cut off by the bytes its connection actually receives (headers, redirects, informational responses and compressed bodies included): the body cap plus 1 MB (for a read, the larger of the page and file caps, since whether a response is a page or a file is known only from its first bytes).
|
|
481
|
-
- Parsing and scanning of page content runs in a worker thread under a time budget (5 seconds by default; set `TIRESIAS_PARSE_BUDGET_MS` to change it). A page that takes longer, or a caller that cancels, ends the worker and the call returns `page_too_complex`. Inputs of 8 KB or less run inline. The worker has a 512 MB heap limit (`TIRESIAS_WORKER_HEAP_MB`; Node's own `--max-old-space-size` flag overrides it); a page that exhausts it also returns `page_too_complex`. JSON that expands past 5 Mi characters of text is cut there and the cut is counted in `text_omitted` (the printer stops at the cap, so the full expansion is never built; `text_omitted` is exact, or a lower bound marked `text_omitted_at_least` for documents nested over 100,000 levels). Some smaller steps (robots parsing, discovery scanning, price parsing, cache handling) still run on the main thread; see the limits below.
|
|
482
|
-
- Page and robots checks use bounded `indexOf` scanning (first 512 KB), never regexes with nested or lazy spans, so a hostile page cannot stall the process. Retry-After is recorded
|
|
483
|
-
- Reads robots.txt (cached 1 hour) per RFC 9309: longest-match Allow/Disallow, `*` and `$`, percent-encoding normalized, CR/LF/CRLF, non-backtracking matcher. Missing robots means allowed. An unreachable or 5xx robots.txt,
|
|
520
|
+
- Parsing and scanning of page content runs in a worker thread under a time budget (5 seconds by default; set `TIRESIAS_PARSE_BUDGET_MS` to change it). A page that takes longer, or a caller that cancels, ends the worker and the call returns `page_too_complex`. Inputs of 8 KB or less run inline, except PDFs, zip and Office files, and calendars, which always run outside the main thread. The worker has a 512 MB heap limit (`TIRESIAS_WORKER_HEAP_MB`; Node's own `--max-old-space-size` flag overrides it); a page that exhausts it also returns `page_too_complex`. JSON that expands past 5 Mi characters of text is cut there and the cut is counted in `text_omitted` (the printer stops at the cap, so the full expansion is never built; `text_omitted` is exact, or a lower bound marked `text_omitted_at_least` for documents nested over 100,000 levels). Some smaller steps (robots parsing, discovery scanning, price parsing, cache handling) still run on the main thread; see the limits below.
|
|
521
|
+
- Page and robots checks use bounded `indexOf` scanning (first 512 KB), never regexes with nested or lazy spans, so a hostile page cannot stall the process. Retry-After is recorded when 429/503 or redirect headers arrive; a redirect asking for a wait is not followed. A challenged redirect also stops the call before it is followed.
|
|
522
|
+
- Reads robots.txt (cached 1 hour) per RFC 9309: longest-match Allow/Disallow, `*` and `$`, percent-encoding normalized, CR/LF/CRLF, non-backtracking matcher. Missing robots means allowed. An unreachable or 5xx robots.txt, a challenged one, or one larger than 512 KB (too large to apply faithfully) means stop. Keeps the longest applicable Crawl-delay in full and declines waits over 30 seconds. Cross-origin robots redirects are followed only to that origin's own `/robots.txt`, with no query; any other path means stop. Retry-After on 429/503 and redirects starts a cooldown that blocks every later request to that site, across runs.
|
|
484
523
|
- Looks for llms.txt, llms-full.txt, `/.well-known/mcp.json`, OpenAPI specs, feeds, sitemaps and JSON-LD. A challenge or 402 on any probe stops the whole call when the probes run before the reply (`doors wait`, private reads); with background door checks (the default) the page already read stands, and the challenge or price stops only the door checks. A bare 401/403 on a probe path only means that door is unavailable; the page itself still gets full wall detection.
|
|
485
524
|
- Reads HTML, markdown, plain text, JSON and PDF.
|
|
486
525
|
- Recognizes 401/403, Cloudflare challenges, CAPTCHA pages and login pages as walls, for any content type.
|
|
487
526
|
- Reads x402 and Cloudflare-style 402 price tags. Never pays.
|
|
488
527
|
- Remembers ETag, Last-Modified and a content hash per final URL, and answers "unchanged" in one line.
|
|
489
|
-
- Flags hidden text (inline-style and attribute based; on a rendered page, as the browser shows it), HTML comments and
|
|
528
|
+
- Flags hidden text (inline-style and attribute based; on a rendered page, as the browser shows it), HTML comments and text aimed at an AI (phrase lists in 13 languages, and since v1.2 the patterns local mode checks) in text, titles, headings, link text and JSON-LD, and leaves hidden text out of the readable text.
|
|
490
529
|
- Every returned block has a receipt whose quote is an exact substring of the extracted text.
|
|
491
530
|
|
|
492
531
|
## What it does not do yet
|
|
@@ -498,7 +537,7 @@ tiresias receipts verify <bundle> # check a bundle offline
|
|
|
498
537
|
- The HTTPS path uses the same pinned lookup but has no local automated test.
|
|
499
538
|
- Long URLs (over 2,048 characters) in links, feeds and sitemaps are left out and counted, never shortened.
|
|
500
539
|
- Cooldowns left in a v0.1.3 JSON store or a v0.1.4 `cooldowns.old.jsonl` are still honored (read only).
|
|
501
|
-
- Retry-After cooldowns are kept in one append-only file (`cooldowns.jsonl`), with no lock and no rotation. Many processes can record cooldowns at once without losing any. The file only grows
|
|
540
|
+
- Retry-After cooldowns are kept in one append-only file (`cooldowns.jsonl`), with no lock and no rotation. Many processes can record cooldowns at once without losing any. The file only grows when a site asks for a wait. The whole file is replayed in bounded chunks when it changes, keeping every unexpired wait; if it cannot be read within its time budget, requests stop. Nothing in Tiresias compacts or deletes it, not even `clear --all`; deleting it by hand is safe only when no Tiresias process is running.
|
|
502
541
|
- The store's parent folders are checked on every call up to your home folder; the home folder itself is trusted. If you reach the store through a symlinked alias in a writable folder, the alias's own folders are not checked (set `TIRESIAS_HOME` to a real path).
|
|
503
542
|
- A Retry-After over 10 years is replaced by a 24 hour cooldown. A JSON-LD record over 5 MiB is skipped and reported.
|
|
504
543
|
- Robots matching has a step budget. A path over 8,192 characters, or a robots.txt too costly to check, is refused rather than guessed.
|
package/data/README.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Data for the meaning check
|
|
2
|
+
|
|
3
|
+
These files serve the optional meaning check in local model mode (`tiresias guard`, W-38 in `docs/SPEC.md`).
|
|
4
|
+
Nothing here is code, and nothing here is read until the owner runs `tiresias guard setup`.
|
|
5
|
+
|
|
6
|
+
## guard-starter.jsonl
|
|
7
|
+
|
|
8
|
+
Test strings for a detector. Each line is one `{ "text", "kind" }` object: an example of text a web page could
|
|
9
|
+
carry to steer an AI that reads it, in the form it would take planted in a page, one to three sentences long. The
|
|
10
|
+
meaning check compares each passage a local model is about to read with these examples. They are not instructions
|
|
11
|
+
for anyone, and Tiresias never shows them to a model.
|
|
12
|
+
|
|
13
|
+
We wrote them for Tiresias. Each kind of trick is written in several ways and set on several unrelated subjects (a
|
|
14
|
+
hotel's check-in page, release notes, a clinic, a recipe, a school calendar, a product review and so on), so the
|
|
15
|
+
library teaches the check the trick and not the topic. A few are in Spanish, French, German, Portuguese and
|
|
16
|
+
Chinese. Whatever the planted text names is a harmless stand-in: invented words in capitals, invented file names,
|
|
17
|
+
phone numbers from 555-0100 to 555-0199, and addresses on `.example`, a name reserved for examples that never reaches a real site.
|
|
18
|
+
|
|
19
|
+
The kinds: `override` (drop the user's question), `fake_system` (poses as the system or a developer), `fake_user`
|
|
20
|
+
(poses as the user), `fake_tool` (imitates Tiresias, a tool result or its end), `fake_assistant` (poses as the
|
|
21
|
+
model's own thinking or memory), `chat_marks` (chat template markers and role lines), `send_out` (open or pass on
|
|
22
|
+
an address, or put the conversation or a secret in an address or image link), `reply_shape` (what to say, add or
|
|
23
|
+
end with), `favour` (a polite request to recommend or mention something), `task_changed`, `fake_rule` (invented
|
|
24
|
+
terms or legal notices for AI readers), `urgency`, `persona`, `secrecy` (keep something from the user) and
|
|
25
|
+
`conditional` ("if you are an AI ...").
|
|
26
|
+
|
|
27
|
+
## guard-ordinary-urls.txt
|
|
28
|
+
|
|
29
|
+
About 100 public pages that `guard setup` reads, through Tiresias and under its usual rules, to gather ordinary
|
|
30
|
+
page text for the check to compare against. Most are everyday pages. The ones under the `about-ai` heading talk
|
|
31
|
+
about models, prompts and prompt injection without attacking anyone: they are the hardest ordinary text for the
|
|
32
|
+
check, and it has to learn to leave them alone. The text gathered from them stays in your own store. Swap the
|
|
33
|
+
list with `--ordinary-urls`, or give your own passages with `--ordinary`.
|