pikuri-thunderbird 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd969845e2b1269b1be2163e7c670cb1fcf04821f9128bc8b89b487e5c4be828
+  data.tar.gz: 6441b467c55043738ad0475c6a3a55bbfdcc1c13c1b5bee7af3cb41d72498f99
+SHA512:
+  metadata.gz: 41c4d6b2bab01c68bd8d3ac522f7f2bef92b17f5c101caa71375129a2d1d1dc4f34ff055781b548e117803c29b5312d5ef50fae2312888a4baaea5939e929f4e
+  data.tar.gz: '06927ce1a93609bc8541f87a6725801688a0387b1b88b8febac84b5c5c94ca192ab1c8405850b60e5120be71f0c6335e8436ef18254c07ea5d4ebb8f9cf78fc3'

data/DESIGN.md

@@ -0,0 +1,460 @@
+# pikuri-thunderbird — design & threat model
+
+Audience: someone extending this gem or auditing its security posture.
+Rationale for individual classes lives in their YARD headers; this file
+covers the cross-cutting design and the threat model. The in-flight design
+notes and still-open questions live in `ideas/thunderbird.md`.
+
+## What it does
+
+Gives a pikuri agent read-only access to the user's **local** Thunderbird
+data — stored mail and cached calendars — by reading Thunderbird's own
+on-disk profile. It never speaks IMAP/POP3/SMTP or CalDAV itself; it reads
+files Thunderbird already wrote.
+
+- **Mail** rides Thunderbird's Gloda index (`global-messages-db.sqlite`),
+  which has already MIME-decoded, HTML-stripped, and split every message
+  into body / subject / attachment-names / author / recipients. pikuri
+  treats it as a pre-decoded corpus.
+- **Calendar** reads the `calendar-data/*.sqlite` stores, whose events are
+  normalized columns (no ICS parser for the common case).
+
+## Threat model: the lethal trifecta
+
+Email is the textbook lethal trifecta. The three legs:
+
+1. **Private data** — the mailbox and calendars. Inherently present.
+2. **Untrusted content** — every message body, subject, and attachment name
+   is authored by whoever sent the mail, i.e. potentially an attacker.
+   Inherently present.
+3. **Egress** — the ability to send data out.
+
+**The default surface removes leg 3 entirely.** The five tools
+`thunderbird_mail_search`, `thunderbird_mail_read`,
+`thunderbird_contact_search`, `thunderbird_calendar_search`, and
+`thunderbird_calendar_read` are all inbound-only, and they are all `Extension`
+gives unless a host opts into an outbound leg. An agent wired with just these (plus, say, a calculator) has legs 1
+and 2 but no way to send anything anywhere, so a prompt injection buried in a
+message body has no exfiltration channel. That is the "trifecta broken by
+construction" posture `bin/pikuri-corpus` and `bin/pikuri-memory` demo.
+
+The bundled `bin/pikuri-thunderbird` deliberately goes one step further — it
+wires both outbound `allow_` flags to demo the *whole* surface — so it does
+carry leg 3. But that leg is human-gated: compose can only open a Thunderbird
+compose window the user Sends themselves (below), so there is an egress leg yet
+no *autonomous* egress. A poisoned message can influence a draft, but cannot make it leave the
+machine without the user clicking Send on a window they can see. So the demo's
+trifecta is *intact-but-gated*, not severed — an honest smoke-alarm, not a
+firewall.
+
+Defense in depth on leg 2: **Spam/Junk/Trash are not searched.** On the
+Gloda path this is *free* — Gloda already assigns those folders indexing
+priority `-1` (never indexed), so the search backend structurally cannot
+return them. This attenuates but does **not** sever leg 2: a *targeted*
+injection lands in the Inbox (a reply, a newsletter, a calendar invite), not
+in Spam. Record it as a mitigation, never a boundary. Honest wrinkle
+(confirmed on a live box): Gmail's account-level Trash folders are `-1`, but
+the `[Gmail]/Trash` *label* folder is indexed at priority 20, so a handful of
+trashed Gmail messages can surface — the free skip is nearly, not perfectly,
+complete.
+
+## The snapshot mechanism
+
+Thunderbird holds its SQLite DBs open with `locking_mode=EXCLUSIVE`, so a
+plain read fails "database is locked" while it runs, and a lock-bypassing
+`immutable=1` read of the live file risks a torn read. pikuri never queries
+the live file. Instead {Pikuri::Thunderbird::DatabaseSnapshot} takes a **bracketed
+`cp --reflink=auto`**: it reads the SQLite change counter (header bytes
+24–27) and checks for a rollback `-journal` before and after the copy, and
+accepts the copy only if the counter didn't move and no journal was present
+at either edge (otherwise it discards and retries). Reflink makes the copy a
+near-free metadata-only extent share on a copy-on-write filesystem.
+
+The validated change counter doubles as a freshness stamp: each query
+compares the live counter against it and re-copies (and, for mail, rebuilds
+the FTS5 index) only when it moved. One signal drives both consistency and
+freshness.
+
+**Mail search index.** Gloda's own full-text index (`messagesText`) is an
+fts3 virtual table behind Mozilla's custom `mozporter` tokenizer, which the
+`sqlite3` gem cannot open. So pikuri builds its *own* ephemeral FTS5 index
+over the decoded columns (`messagesText_content`) inside the snapshot copy —
+external-content, so it stores only the index, not a second copy of the
+text. Rebuilt (~1 s) only when the Gloda generation moves.
+
+### Privacy caveat
+
+The snapshot is the decoded mailbox/calendar landing **outside** the
+Thunderbird profile, in a `0700` dir under `~/.cache/pikuri/thunderbird/`.
+This is a second at-rest copy — but at the *same trust level* as the source:
+the Gloda and calendar DBs are already unencrypted plaintext on disk in the
+profile, and the copy is user-owned with the same permissions. It is not a
+new exposure class. The copy is `Pikuri::Finalizers`-reaped on a clean exit;
+a crash can strand it until it's next overwritten or the dir is cleared
+(re-derivable data, low harm).
+
+The credential stores that share the profile directory (`logins.*`,
+`key4.db`, `cert9.db`, `openpgp.sqlite`, …) are **never** opened — the
+backends touch only `global-messages-db.sqlite` and `calendar-data/*.sqlite`.
+
+## Outbound is a human-gated v2, never an autonomous send
+
+Composing a mail or creating a calendar event is egress (a send, an invite,
+a CalDAV sync). The design invariant, locked in before any of it ships:
+
+> **pikuri-thunderbird performs no network egress and no autonomous send.**
+> Every outbound action is a hand-off to Thunderbird's own UI — a pre-filled
+> compose window (via a `mailto:` URI) or an `.ics` import wizard — where the
+> *human* reviews and commits. pikuri writes nothing to Thunderbird's stores
+> and sends nothing itself. No send tool ever ships.
+>
+> **And no attachment ever ships.** The outbound surface carries only fields
+> that *render literally*: a plain-text body, a subject, addresses. No
+> attachment of any kind (`.png`, `.zip`, `.txt` — the extension is
+> irrelevant), no HTML body, no iCalendar `ATTACH` property.
+
+This converts egress from *agent-automatic* to *human-action-required*. Note
+what that does and does not buy — the leg is **downgraded, not removed**, and
+the threat-model section above is the authority: once an `allow_` flag is on,
+leg 3 is present. Only the default surface (both flags off) severs it.
+
+What the downgrade rests on is narrow and worth naming, because it's the one
+property a rubber-stamping human can't destroy: **the human sees the exact
+bytes that leave.** The compose window shows the literal recipient, subject
+and body that will be sent; the `.ics` wizard shows the event that will be
+imported. Contrast a shell agent that asks "run `curl …`?" — there the human
+approves a *program*, and what it actually uploads was never on screen. So a
+poisoned message can influence a draft, but every byte of that draft was
+displayed to someone before it moved.
+
+That is a real reduction and not a boundary: it kills *silent* exfil — every
+byte was on a screen — and leaves the covert channel, a secret spelled into
+prose the reader skims past, sent as a reply to the injector (see "What the
+body guards do *not* close" below).
+
+**Resist the temptation to call the survivors low-bandwidth.** They aren't.
+A first-letter acrostic carries roughly one letter per word, and a secret is
+already text — so an agent *transcribes* it rather than computing anything.
+Price the channel that way, since this gem wires no shell and no calculator:
+a pasted `id_ed25519` is its ~400 base64 characters, so ~400 words; a whole
+RSA PEM ~1600. A thread, not a wall — and the mailbox is exactly where
+someone pasted the key "just to have it" five years ago. (An agent that
+*does* hold local compute prices it lower still, by the secret's entropy —
+~55 words for that ed25519 key; a network-severed sandbox cuts egress, never
+arithmetic. See `book/os-assistant.md` §"Why 'too big to hide' is not a
+defense".) The bytes-visible property is worth stating because it is
+structural; "the payload is too big to hide" is not, and shouldn't be
+offered as reassurance.
+
+### Why no attachments — it's the same invariant as plain-text-only
+
+An attachment is the cleanest way to defeat the whole gate. A key encoded in
+the low bits of a `.png` is invisible to any reader: the human approves a
+*filename* and a thumbnail, never the bytes. That is exactly the shape of a
+shell agent asking "run `curl …`?" — an approved *reference* to content
+nobody saw — and it would demote this hand-off from "human sees the payload"
+to the same class as an autonomous send, no matter how careful the human is.
+
+So "plain text only" and "no attachments" are not two policies but one:
+**the outbound surface may contain only fields whose rendering is their
+content.** HTML fails it (`<span style="display:none">`), attachments fail it,
+and so would any richer field added later. Today this is enforced by
+construction rather than by filtering — {Pikuri::Thunderbird::MailtoUri}
+*builds* an allowlist of five parameters (`to`/`cc`/`bcc`/`subject`/`body`),
+so there is no `attach=` to strip, and {Pikuri::Thunderbird::IcsEvent} emits
+no `ATTACH` property. Enforced-by-absence is fragile against a future
+"improvement" — `mailto:?attach=` was a real Thunderbird feature — which is
+why the invariant is written down rather than left implied by the code.
+
+**Compose is shipped, opt-in.** `thunderbird_mail_compose`
+({Pikuri::Thunderbird::MailCompose}) is wired only when a host passes
+`Extension.new(allow_compose_mail: true)` — off by default, so an unopted wiring has no
+egress leg *by construction*. `bin/pikuri-thunderbird` opts in (to demo the
+full surface). Turning compose on re-introduces leg 3, but only as a
+human-committed hand-off: the tool opens a
+`mailto:` compose window ({Pikuri::Thunderbird::MailtoUri} percent-encodes every
+field so a body can't smuggle `&bcc=`), the body is plain-text-only (no hidden
+content, no remote beacons), and a mechanical recipient guard
+({Pikuri::Thunderbird::ComposeGuard}) runs first: a suspicious *body* fails
+closed; suspicious/non-ASCII/punycode *recipients* are dropped for the human to
+retype; a never-corresponded-with recipient domain (per
+{Pikuri::Thunderbird::Gloda#domains_seen}) is flagged, not blocked; and a body
+carrying a long base64 *blob* earns a located soft-warn (see
+{Pikuri::Thunderbird::ComposeGuard#body_blob_note}). The launch
+is detached (`setsid --fork`) so closing the agent never kills the user's
+Thunderbird.
+
+**What the body guards do *not* close.** They raise attention on the lazy exfil
+— a control-byte/homoglyph body fails closed, a base64/hex/base32 dump earns a
+note — but
+they are not a barrier against an *adaptive* injector, who splits the blob with
+whitespace or spells it in prose for free (the same injection payload carries
+the evasion). The sharpest surviving channel is **reply-to-injector**: the
+poisoning message's From-domain is already in Gloda's identities graph (which
+counts received mail, both directions), so a reply to the attacker draws no
+novelty flag. The check is also per-*domain*, so a never-seen address at a
+domain you have mailed before is silent as well.
+
+**What each guard really buys is a rung, not a wall.** Every check here
+narrows the *form* the payload may take, never the payload itself, so an
+adaptive injector simply steps down: fail the body on control bytes,
+zero-width joiners and homoglyphs, and it drops to plain ASCII; note a
+base64 dump and it moves to hex, then base32, then splits the run below the
+threshold; catch those and what remains is **linguistic steganography** — the
+secret spelled out by the first letters of an innocuous sentence ("I think
+dogs are super cute"), by word choice, by sentence count. That bottom rung
+reads as ordinary prose to the guards *and* to the human, which is where an
+injector who has read this file starts. It is slower, and slow is not a
+barrier: `book/os-assistant.md` §"Why 'too big to hide' is not a defense"
+prices what fits. The human-gated, irreversible-send compose window — not the
+guard — is the backstop all of this leans on.
+
+**Create-event is shipped, opt-in.** `thunderbird_calendar_create`
+({Pikuri::Thunderbird::CalendarCreate}) is wired only when a host passes
+`Extension.new(allow_create_calendar_event: true)`. Same human-gated shape:
+it builds an event `.ics` ({Pikuri::Thunderbird::IcsEvent} RFC-5545-escapes
+every field so a description can't inject a second `VEVENT`), stages it where a
+snap-confined Thunderbird can read it ({Pikuri::Thunderbird::Profile#outbox_dir}),
+and hands it to TB's import wizard, where the human picks the destination
+calendar (local-vs-CalDAV = their no-egress-vs-egress choice) and confirms.
+Both outbound tools launch via the shared {Pikuri::Thunderbird::Launcher}. The
+full v2 rationale + open questions are in `ideas/thunderbird.md`.
+
+## Discovery
+
+{Pikuri::Thunderbird::Profile} never guesses: it resolves one profile
+unambiguously (parsing `profiles.ini`), raises with a fix if two install
+roots both hold a profile (a stale apt profile left after an apt→snap
+migration), or returns `nil` (tools simply not registered) when Thunderbird
+isn't installed. An explicit `profile_dir:` override bypasses discovery.
+Linux snap and apt roots are supported; flatpak is out of scope.
+
+## Storage landscape (empirically confirmed)
+
+The reference data the design rests on, probed against a live snap install
+(Thunderbird 152.0, Linux, 2026-07). It's here — not in the class yardocs —
+because it spans the whole gem and is expensive to re-derive (it needs a real,
+populated Thunderbird). The per-symbol *why* lives in the class yardocs; this
+is the shared evidence base, and the ground truth a v2 builder will need.
+
+Caveat: all of this is one real install (snap; Gmail + iCloud IMAP; CalDAV
+calendars). The code is otherwise tested only against synthetic fixtures built
+to this schema — a first run against a real profile is still the true smoke
+test.
+
+### Profile & install roots
+
+- `profiles.ini` is a small INI; the active profile is the `Default=1`
+  section (`Path`, relative when `IsRelative=1`). The confirmed real file has
+  **no `[Install…]` sections** (Firefox's per-install mechanism), so the plain
+  `Default=1` scan suffices.
+- Roots: **snap** `~/snap/thunderbird/common/.thunderbird/` (confirmed),
+  **apt** `~/.thunderbird/` (recalled). Flatpak
+  (`~/.var/app/org.mozilla.Thunderbird/…`) is out of scope.
+- `.parentlock` at the profile root is Thunderbird's running-instance lock — a
+  cheap "is TB open?" probe.
+
+### Mail: the Gloda index (`global-messages-db.sqlite`) — the v1 source
+
+A complete, pre-decoded search index. Tables that matter:
+
+- **`messagesText`** — an FTS3 virtual table over `body`, `subject`,
+  `attachmentNames`, `author`, `recipients` (already MIME-decoded,
+  HTML-stripped, attachment *names* extracted). Its backing store is the plain
+  table **`messagesText_content(docid, c0body, c1subject, c2attachmentNames,
+  c3author, c4recipients)`**.
+- **`messages`** — `id` (= FTS `docid`), `folderID`, `messageKey`,
+  `conversationID`, `date` (**PRTime = µs since epoch**, ÷1e6 for Unix
+  seconds, second granularity), `headerMessageID` (the RFC822 `Message-ID`),
+  **`deleted`**, `jsonAttributes`, `notability`.
+- **`folderLocations`** — `id`, `folderURI`, `dirtyStatus`, `name`,
+  **`indexingPriority`**: `-1` = never indexed (Gloda's sentinel), else `20`
+  (normal) / `50` (INBOX) / `60` (Sent). Resolves a hit's `folderID` → folder.
+- **`contacts` / `identities` / `contactAttributes`** — the email↔name
+  correspondence graph. `contacts` is **dead for resolution** — `frecency` /
+  `popularity` are 0 for every row and `name` is unreliable (often a bare
+  address or junk), so {Pikuri::Thunderbird::Gloda::Contacts#resolve} reads the
+  *decoded* `c3author` / `c4recipients` columns instead (name + address
+  together, with a natural per-message frequency). `identities(kind, value)` —
+  where `kind='email'`, `value` the bare address — *is* used, by
+  {Gloda::Contacts#domains_seen} for the recipient-novelty warn.
+- **`attributeDefinitions` / `messageAttributes`** — extensible per-message
+  attributes; ids seen: 57 `tag`, 58 `star`, 59 `read`, 60 `repliedTo`,
+  61 `forwarded`. (Relevant to churn — see the change counter below.)
+- Ignore: `imConversations*`, `ext_mimeTypes`.
+
+**The mozporter sharp edge.** Both FTS tables use Mozilla's custom `mozporter`
+tokenizer, so a stock SQLite (CLI *or* the `sqlite3` gem) cannot `… MATCH …`
+against them — it errors *"unknown tokenizer: mozporter"*. Worse, the gem's
+precompiled SQLite (3.53.2) is built **FTS5-only**, so it can't even *open*
+Gloda's fts3 `messagesText` (`no such module: fts3`). Registering a mozporter
+tokenizer `.so` was tested and is a dead end on the default stack (it needs a
+bespoke FTS3-compiled SQLite build, not just a loadable tokenizer). Escape:
+read the plain `messagesText_content` columns directly (openable fine) and
+build our own FTS5 over them — which is exactly what {Pikuri::Thunderbird::Gloda}
+does. (`c0body LIKE '%invoice%'` scanned cleanly, 234 hits, on the real box.)
+
+**Freshness/consistency: the change counter.** `journal_mode=delete` (classic
+rollback journal, no WAL), `user_version=30` (a drift anchor). The file change
+counter (header bytes 24–27) is authoritative per commit here, bumped only on
+unlock-after-write (a read never moves it). Measured: it bumps on *any* Gloda
+write — **including read/star/tag flips during triage** (marking one message
+unread advanced it +1), not only new-mail arrivals — because Gloda indexes
+those as attributes. Consequence for the FTS5 rebuild: it re-fires during
+ordinary triage, not just after a poll (a ~1 s papercut; a future optimization
+gates the rebuild on a content triple `(max(id), count(*), sum(deleted))`
+instead of the raw counter). The `-journal` is **transient, not persistently
+retained** (probed: present in 1 of 3 idle samples, exactly while the counter
+was mid-bump), so its presence is a valid "write in flight → retry" signal for
+the snapshot bracket.
+
+**Gmail label fan-out (why dedup is mandatory).** Gmail exposes each label as
+an IMAP folder, so a message with N labels yields N Gloda rows.
+**`[Gmail]/All Mail` is indexed** (`indexingPriority` 20, **5974 messages** —
+the largest folder, vs. 8239 distinct Message-IDs / 9654 total rows → ~1415
+duplicate rows). Search dedups by `headerMessageID` before the top-N cap. The
+7 `-1` never-indexed folders are exactly Trash/Spam/Junk/Unsent across the
+accounts — so the "skip Spam" leg-2 attenuation is free on the Gloda path —
+**except `[Gmail]/Trash` is indexed at prio 20** (5 msgs), so that skip is
+nearly, not perfectly, complete. (Also seen: 1571 rows with a null/blank
+`folderID` — irrelevant to Gloda-only reads, which take the body from
+`c0body`.)
+
+### Mail: mbox on disk (the unbuilt fallback's substrate)
+
+Not used by v1 (Gloda serves it fully); recorded for the deferred family-B
+fallback. Mail is **mbox** (extensionless files, `file(1)` "Mailbox text"),
+under `ImapMail/<server>/` (IMAP, subfolders nest via `<Folder>.sbd/`) and
+`Mail/` (Local Folders, Feeds); each mbox is shadowed by a `<Folder>.msf`
+**Mork** summary (ignorable — Gloda has the decoded text + folder map). A
+correct mbox reader would need: CRLF line endings; the dash-prefixed
+`From - <ctime>` separator (not classic `From <addr>`); server-defined folder
+names (Gmail INBOX is uppercase — never hardcode); and honoring the
+`X-Mozilla-Status`/`Status2` **deleted-but-not-compacted** bit. `messageKey`
+is *not* a universal seek offset — IMAP UID for `ImapMail/`, byte offset only
+for local `Mail/` — which is why a Gloda→mbox hybrid read was rejected.
+
+### Calendar stores (`calendar-data/`)
+
+Three sibling DBs: **`cache.sqlite`** (cached network/CalDAV calendars),
+**`local.sqlite`** (`storage`-type local calendars), `deleted.sqlite`
+(`cal_deleted_items` sync tombstones). **The data gate:** a CalDAV calendar
+keeps events **in memory only** unless "Offline Support" (`cache.enabled` in
+`prefs.js`) is on — so all three can be empty while the UI shows full
+calendars. Enabling it populated `cache.sqlite` to **62 MB / 5414 events** and
+it mirrors `local.sqlite`'s schema exactly (`cal_calendar_schema_version=23`;
+`user_version` is 0 — gate on the table, not the pragma). This is why the
+calendar tools register regardless and self-explain the empty state.
+
+`cal_events` is normalized columns, not opaque ICS:
+
+- `cal_id` (the calendar's registry UUID → `prefs.js`
+  `calendar.registry.<uuid>.{name,type,uri,cache.enabled}` for human name +
+  `storage`/`caldav` type), `id` (event UID), `title`.
+- `event_start`/`event_end` — **PRTime µs of the UTC instant** (confirmed on
+  5414 events: sane 2010→2031 histogram; times read as business hours only
+  under UTC→local; user-confirmed against the live UI — a 10:00 meeting reads
+  10:00 local, not 07:00 UTC). Displayed via the `_tz` column.
+- `event_start_tz`/`event_end_tz` — a tzid string, and the two **can differ**
+  (cross-zone events). Valid forms, all meaningful: Olson names
+  (`Europe/Helsinki` dominant), literal **`floating`** (wall-clock; every
+  all-day event uses it), **`UTC`**, rare fixed-offset **`GMT+0300`**. Default
+  defensively even though no null was observed.
+- `flags` = calStorageCalendar's `CAL_ITEM_FLAG` bitfield (verify against
+  comm-central at v2 impl): 2=attendees, 4=properties, **8=all-day**,
+  16=recurrence, 32=exceptions, 64=attachments, 128=relations, 256=alarms,
+  512=recurrence-id-all-day. **All-day = bit 8** — airtight (a clean diagonal:
+  126 rows, `flags&8` ⟺ midnight-aligned start ⟺ `tz=floating`, zero
+  off-diagonal). All-day DTEND is iCal **exclusive** (1-day event spans exactly
+  1 day), so render `[start, end − 1 day]` and don't zone-convert.
+- `ical_status`, `priority`, `privacy`, recurrence fields. **`recurrence_id`**
+  is the fold key: a recurring series is stored as a *master* row
+  (`recurrence_id` NULL, `flags & 16` set, RRULE in `cal_recurrence`) **plus one
+  row per modified occurrence** ("exception") — same event UID, distinct
+  `recurrence_id` (the occurrence's PRTime), and *no* `flags & 16` bit. So a
+  per-row recurrence filter on `flags & 16 = 0` leaks every occurrence under
+  "single" and floods plain search with the same event; `Calendar#search` folds
+  rows by UID (`#fold_series`) and classifies the *series* recurring if any row
+  is a master or an occurrence.
+
+Companions: `cal_todos` (VTODO, same shape); `cal_properties(item_id, key,
+value)` (DESCRIPTION, LOCATION, …); `cal_recurrence`/`cal_attendees`/
+`cal_alarms`/`cal_relations`/`cal_attachments` (iCal-shaped `icalString`
+fragments — parse with the `icalendar` gem only if wanted).
+
+### SQLite locking
+
+Thunderbird opens its DBs with `locking_mode=EXCLUSIVE`, so a plain
+`-readonly` open fails *"database is locked (5)"* while it runs — **even for
+WAL stores** (the calendar DBs are WAL, and WAL readers are still shut out).
+`immutable=1` is the universal lock-bypass; for a WAL store it reads
+as-of-last-checkpoint (Thunderbird checkpoints aggressively — right after the
+62 MB sync the `-wal` held ~1 MB and `immutable=1` saw all 5414 events). This
+is why {Pikuri::Thunderbird::DatabaseSnapshot} works against a *copy*, not the live
+file. (WAL caveat for calendar freshness: a WAL DB's change counter bumps only
+on checkpoint, so calendar staleness should eventually pair the counter with
+`-wal` size+mtime — deferred; v1 uses the counter.)
+
+### Platform confinement (snap `home` interface)
+
+Mapped by staging a probe `.ics` in three spots and opening each in a
+snap-confined Thunderbird:
+
+| Location | Readable by snap TB? |
+|---|---|
+| snap-owned area (`~/snap/thunderbird/common/…`) | **yes** |
+| hidden home dir (`~/.cache/…`) | **no** |
+| non-hidden home (`~/…`) | **yes** |
+
+The recalled dotfile restriction is real: the `home` interface grants
+non-hidden `$HOME` files, not dotfiles. **Sharp UX edge:** a blocked path does
+*not* error — the `.ics` import wizard opens and reports "no events available"
+(it read an empty file) — so staging correctness can't lean on error
+detection. Consequence: the v1 snapshot lives in hidden `~/.cache` (read by
+*pikuri*, unconfined — fine), but a v2 `.ics` hand-off must stage where the
+confined TB reads (snap-owned area, or a non-hidden `$HOME` dir); the two dirs
+can't be shared on snap.
+
+### Hand-off mechanics — for the v2 egress tools
+
+- **Compose → `mailto:` URI (built).** `thunderbird 'mailto:to@…?cc=…&bcc=…&subject=…&body=First%0ASecond'`
+  opens a pre-filled compose window, percent-decoding cleanly (`%0A`→newline,
+  `%20`→space), populating subject + cc + **bcc**, reusing the running
+  instance. Chosen over `-compose`, which **cannot do multiline** (`body='A%0AB'`
+  rendered the literal `A%0AB`). Because the transport is a URI, every field
+  value must be percent-encoded so an attacker-authored body can't smuggle a
+  hidden `&bcc=` — see {Pikuri::Thunderbird::MailtoUri}. pikuri launches it
+  detached (`setsid --fork`) so the agent's exit-sweep can't SIGTERM the user's
+  Thunderbird, and so a not-yet-running Thunderbird doesn't block the tool on
+  the GUI.
+- **Create event → `.ics` import (built).** `thunderbird <path.ics>` opens TB's
+  "Import Calendar file" wizard as a new tab (running-instance reuse): a 4-step
+  flow ending in **Confirm**, with a **target-calendar picker** at step 3.
+  **No silent import** — Cancel leaves nothing behind. So TB's UI owns the
+  commit *and* the human picks local-vs-CalDAV (i.e. no-egress-vs-egress). The
+  `.ics` is built by {Pikuri::Thunderbird::IcsEvent} (RFC-5545 field escaping is
+  the injection defense), staged in {Pikuri::Thunderbird::Profile#outbox_dir}
+  (confined-readable, **not** the hidden `~/.cache` snapshot dir — see § "Platform
+  confinement"), and handed off by the shared {Pikuri::Thunderbird::Launcher}
+  (the same detached `setsid --fork` launch compose uses).
+
+Both are the human-gated hand-off shape the no-send seam requires: pikuri
+opens a window, the human reviews and commits.
+
+### Files never touched
+
+The guarantee is an **allowlist, not a blocklist**: the backends open only
+`global-messages-db.sqlite` and `calendar-data/*.sqlite` (plus their snapshot
+copies), and discovery reads `profiles.ini`. Nothing else in the profile
+directory is ever opened — so no enumeration of what-to-avoid is load-bearing,
+and a wrong name below changes nothing.
+
+For orientation, the profile dir (the same dir as the Gloda file) also holds
+the credential/secret stores pikuri stays clear of: the NSS key/cert databases
+`key4.db` + `cert9.db`, saved passwords `logins.json` + `logins-backup.json`,
+and Thunderbird's OpenPGP key material (including
+`encrypted-openpgp-passphrase.txt`). These names are **recalled from the
+Firefox/Thunderbird profile layout, not probe-confirmed and not exhaustive**
+(verify against a real profile if it ever matters — but it doesn't, given the
+allowlist). Browser/telemetry cruft (`places.sqlite`, `cookies.sqlite`,
+`favicons.sqlite`, `storage/`, `datareporting/`, …) is likewise untouched.

data/README.md

@@ -0,0 +1,66 @@
+# pikuri-thunderbird
+
+Search and read your **local** Thunderbird mail and calendars from a pikuri
+agent — reading Thunderbird's own on-disk profile, never touching the
+network. Part of the [pikuri](https://codeberg.org/mvysny/pikuri) family.
+
+The default surface is read-only and egress-free: four inbound tools
+(`thunderbird_mail_search` / `thunderbird_mail_read` /
+`thunderbird_calendar_search` / `thunderbird_calendar_read`). An agent wired
+with only these has your private mailbox and untrusted message content but no
+way to send anything out — the lethal trifecta is broken by construction.
+
+pikuri never sends mail on its own. If you turn on the opt-in
+`thunderbird_mail_compose` tool, the most it can do is **open a pre-filled
+Thunderbird compose window** — you read it, and *you* click Send. It draws the
+draft in plain text (no hidden HTML, no tracking images), refuses a body laced
+with invisible characters, drops look-alike recipient addresses for you to
+retype, and warns you when you're about to mail a domain you've never
+corresponded with. See [`DESIGN.md`](DESIGN.md).
+
+## Requirements
+
+- Linux, with Thunderbird installed (snap or apt).
+- For mail search: Thunderbird's global search index (Gloda) enabled — the
+  default. For calendar: events must be cached to disk (a local calendar, or
+  a network calendar with "Offline Support" turned on).
+
+## Try it
+
+```sh
+./bin/pikuri-thunderbird "what did Alice say about the invoice last month?"
+```
+
+It auto-discovers your active Thunderbird profile. Point it elsewhere with
+`--profile-dir /path/to/profile`. This demo wires the full surface, including
+the compose hand-off — ask it to reply to a message and it opens a pre-filled
+Thunderbird window for you to send (it never sends by itself). The demo talks
+to a local llama.cpp server by default; put your LLM connection in
+`~/.pikuri-examples-config.yaml` (`llm_server`, `llm_model`, `llm_api_key`).
+
+## Wire it into your own agent
+
+```ruby
+require 'pikuri-thunderbird'
+
+agent = Pikuri::Agent.new(transport:, system_prompt:) do |c|
+  c.add_extension Pikuri::Thunderbird::Extension.new
+end
+```
+
+Mail tools register only when the Gloda index is present; calendar tools
+register whenever a profile is found (and guide you to enable Offline Support
+if nothing is cached yet). To add an outbound hand-off, pass
+`Extension.new(allow_compose_mail: true)` (draft a message) or
+`allow_create_calendar_event: true` (draft a calendar event) — each stays off
+unless you ask for it, and your `system_prompt` should then tell the model it
+may draft for you to send/import (an inbound-only prompt that forbids sending
+will keep the tools unused).
+
+## How it works
+
+pikuri copies a consistent snapshot of Thunderbird's SQLite databases (so it
+never fights Thunderbird for the lock), builds its own fast full-text index
+over the already-decoded mail, and serves ranked search + full reads with no
+MIME parsing. Design and threat model: [`DESIGN.md`](DESIGN.md). In-flight
+design notes: `ideas/thunderbird.md` in the repo.