@raibitsi/tiresias 1.1.0 → 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 CHANGED
@@ -2,6 +2,49 @@
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
+
5
48
  ## v1.1.0 (2026-11-10)
6
49
 
7
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.
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 (PDFs cannot be read there, and your own scanner and translator do not run there).
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 share only the minimal politeness state, origin and times; `private_spacing=none` disables that sharing after confirmation).
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).
@@ -131,6 +131,20 @@ Tools (18): `read`, `doors`, `check`, `receipts`, `history`, `log`, `needs_repor
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. 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. 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
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
 
@@ -314,7 +328,7 @@ tiresias profile remove client-a --yes # add --delete-key if it has a sig
314
328
  - Without `--profile`, Tiresias uses the `default` profile, which is the store folder itself, exactly as before. Existing stores need no change.
315
329
  - Other profiles live in `~/.tiresias/profiles/<name>/`. A profile that does not exist is an error: using it never creates it.
316
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`.
317
- - 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 one second between requests; old entries are removed by the daily trim).
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).
318
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.
319
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).
320
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`.
@@ -396,7 +410,7 @@ Every successful read (`ok` or `unchanged`, not private) opens a numbered tab. `
396
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.
397
411
 
398
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.
399
- - **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 1-second spacing), `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`.
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`.
400
414
 
401
415
  The v1.1 choices are settings too, changed only through the command line or `config.json`:
402
416
 
@@ -407,6 +421,8 @@ The v1.1 choices are settings too, changed only through the command line or `con
407
421
  | `hook_secrets` | `hidden`: hooks do not receive Tiresias secret variables | `inherit`: hooks receive the full environment |
408
422
  | `text_views` | `marked`: readable text with an untrusted-content marker | `wrapped`: text inside `untrusted_content`, like JSON |
409
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
+
410
426
  Set them with `tiresias settings set <name> <value>`; `tiresias settings` shows their defaults and current values.
411
427
  The two loosenings need `--confirm "YES, TURN OFF PRIVATE SPACING"` for `private_spacing none`, or
412
428
  `--confirm "YES, SHARE TIRESIAS SECRETS WITH HOOKS"` for `hook_secrets inherit`. Like other risky settings,
@@ -450,7 +466,7 @@ tiresias settings set rendering off # the default: never
450
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).
451
467
 
452
468
  The page's JavaScript is treated as hostile:
453
- - **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.
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.
454
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.
455
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.
456
472
 
@@ -485,7 +501,7 @@ Prove later that a receipt existed at a given time and has not been edited since
485
501
  ```
486
502
  tiresias settings set anchoring on --confirm "YES, TURN ON ANCHORING" # CLI or config.json, confirmed; never over MCP
487
503
  tiresias anchor # one batch of everything new; run it by hand or from cron
488
- tiresias anchor status # the batches: pending, or in which Bitcoin block
504
+ tiresias anchor status # the batches: pending, or the Bitcoin block a calendar reported
489
505
  tiresias anchor upgrade # ask the calendars whether pending batches reached a block
490
506
  tiresias receipts # each record shows its record_fingerprint
491
507
  tiresias receipts prove <record_fingerprint> --out <folder> # the proof bundle, the record and a standard .ots file
@@ -493,7 +509,7 @@ tiresias receipts verify <bundle> # check a bundle offline
493
509
  ```
494
510
 
495
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.
496
- - **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.
497
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.
498
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).
499
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`
@@ -503,13 +519,13 @@ tiresias receipts verify <bundle> # check a bundle offline
503
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).
504
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.
505
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.
506
- - 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, or a challenged one, 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.
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.
507
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.
508
524
  - Reads HTML, markdown, plain text, JSON and PDF.
509
525
  - Recognizes 401/403, Cloudflare challenges, CAPTCHA pages and login pages as walls, for any content type.
510
526
  - Reads x402 and Cloudflare-style 402 price tags. Never pays.
511
527
  - Remembers ETag, Last-Modified and a content hash per final URL, and answers "unchanged" in one line.
512
- - Flags hidden text (inline-style and attribute based; on a rendered page, as the browser shows it), HTML comments and phrases aimed at an AI in text, titles, headings, link text and JSON-LD, and leaves hidden text out of the readable text.
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.
513
529
  - Every returned block has a receipt whose quote is an exact substring of the extracted text.
514
530
 
515
531
  ## What it does not do yet
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`.
@@ -0,0 +1,102 @@
1
+ # ordinary pages
2
+ https://en.wikipedia.org/wiki/Oedipus
3
+ https://en.wikipedia.org/wiki/Connecticut
4
+ https://en.wikipedia.org/wiki/Sourdough
5
+ https://en.wikipedia.org/wiki/Mortgage
6
+ https://en.wikipedia.org/wiki/Photosynthesis
7
+ https://en.wikipedia.org/wiki/Apollo_11
8
+ https://en.wikipedia.org/wiki/Jazz
9
+ https://en.wikipedia.org/wiki/Bicycle
10
+ https://en.wikipedia.org/wiki/Email
11
+ https://en.wikipedia.org/wiki/Customer_service
12
+ https://en.wikipedia.org/wiki/Password
13
+ https://en.wikipedia.org/wiki/Technical_support
14
+ https://en.wikipedia.org/wiki/Instruction_manual
15
+ https://en.wikipedia.org/wiki/Recipe
16
+ https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402
17
+ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
18
+ https://developer.mozilla.org/en-US/docs/Learn/Forms/Your_first_form
19
+ https://docs.python.org/3/library/json.html
20
+ https://docs.python.org/3/tutorial/introduction.html
21
+ https://docs.python.org/3/library/subprocess.html
22
+ https://nodejs.org/en/learn/getting-started/introduction-to-nodejs
23
+ https://www.rfc-editor.org/rfc/rfc9421.html
24
+ https://www.rfc-editor.org/rfc/rfc9110.html
25
+ https://www.uscis.gov/i-765
26
+ https://www.irs.gov/
27
+ https://www.irs.gov/filing
28
+ https://www.usa.gov/
29
+ https://www.usa.gov/passport
30
+ https://www.cdc.gov/flu/about/index.html
31
+ https://www.nasa.gov/
32
+ https://www.nps.gov/yell/index.htm
33
+ https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business
34
+ https://www.consumerfinance.gov/consumer-tools/mortgages/
35
+ https://www.bbc.com/news
36
+ https://arstechnica.com/
37
+ https://www.theverge.com/
38
+ https://www.theguardian.com/us
39
+ https://www.nytimes.com/
40
+ https://news.ycombinator.com/
41
+ https://vuejs.org/guide/introduction.html
42
+ https://react.dev/learn
43
+ https://angular.dev/overview
44
+ https://svelte.dev/docs/svelte/overview
45
+ https://docs.github.com/en/get-started
46
+ https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-strong-password
47
+ https://stripe.com/docs
48
+ https://pypi.org/project/requests/
49
+ https://www.webmd.com/
50
+ https://www.coursera.org/
51
+ https://www.espn.com/
52
+ https://weather.com/
53
+ https://discord.com/
54
+ https://www.kayak.com/
55
+ https://www.walmart.com/
56
+ https://www.target.com/
57
+ https://www.etsy.com/
58
+ https://www.airbnb.com/
59
+ https://open.spotify.com/
60
+ https://www.notion.so/
61
+ https://www.figma.com/
62
+ https://substack.com/
63
+ https://www.allrecipes.com/
64
+ https://www.mayoclinic.org/healthy-lifestyle/nutrition-and-healthy-eating/in-depth/water/art-20044256
65
+ https://www.investopedia.com/terms/m/mortgage.asp
66
+ https://support.google.com/accounts/answer/32040
67
+ https://support.apple.com/en-us/102660
68
+ https://www.gnu.org/licenses/gpl-3.0.html
69
+ https://www.apache.org/licenses/LICENSE-2.0
70
+ https://choosealicense.com/
71
+ https://example.com/
72
+ # about-ai: pages that talk about models, prompts and assistants without attacking anyone
73
+ https://en.wikipedia.org/wiki/Prompt_injection
74
+ https://en.wikipedia.org/wiki/Prompt_engineering
75
+ https://en.wikipedia.org/wiki/Large_language_model
76
+ https://en.wikipedia.org/wiki/Intelligent_agent
77
+ https://en.wikipedia.org/wiki/Chatbot
78
+ https://en.wikipedia.org/wiki/ChatGPT
79
+ https://en.wikipedia.org/wiki/Jailbreak_(computer_science)
80
+ https://en.wikipedia.org/wiki/Robots.txt
81
+ https://lmstudio.ai/docs/app/mcp
82
+ https://lmstudio.ai/docs/developer/openai-compat/tools
83
+ https://docs.ollama.com/capabilities/tool-calling
84
+ https://docs.ollama.com/modelfile
85
+ https://modelcontextprotocol.io/docs/getting-started/intro
86
+ https://modelcontextprotocol.io/specification/2025-06-18/server/tools
87
+ https://huggingface.co/docs/transformers/main/en/chat_templating
88
+ https://huggingface.co/Qwen/Qwen2.5-7B-Instruct
89
+ https://huggingface.co/meta-llama/Llama-Prompt-Guard-2-22M
90
+ https://huggingface.co/models
91
+ https://ollama.com/library
92
+ https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
93
+ https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/system-prompts
94
+ https://simonwillison.net/2025/Jun/13/prompt-injection-design-patterns/
95
+ https://simonwillison.net/series/prompt-injection/
96
+ https://genai.owasp.org/llmrisk/llm01-prompt-injection/
97
+ https://llmstxt.org/
98
+ https://github.com/Raibit-AI/tiresias
99
+ https://github.com/openai/openai-cookbook
100
+ https://www.anthropic.com/research/prompt-injection-defenses
101
+ https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/prompt-engineering
102
+ https://cookbook.openai.com/