Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .claude/rules/trust-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ paths:
- "shared/original.ts"
- "shared/live.ts"
- "shared/sending.ts"
- "shared/rules.ts"
- "shared/rules-schema.ts"
- "workers/lib/rule-facts.ts"
- "migrations/**"
- ".github/**"
- ".claude/settings.json"
Expand Down
26 changes: 13 additions & 13 deletions .claude/skills/podbay-security/SKILL.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion .claude/skills/podbay-testing/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Put a test in the lowest tier that can prove the rule. A rule about access is pr

## 2. What exists already

**Tier 3, `test/workerd/helpers.ts`:** `migrate`, `setupOwner`, `seedUser`, `seedMembership`, `signIn`, `request` (sends the app's own `Origin`), `createMailbox`, `mime` and `inbound` (a message for the `email` handler), `ageSessions` (make a session old instead of waiting), and `Browser`: a cookie-keeping client with a client address of its own, so the per-address sign-in limits do not couple tests. `enableApp`, `registerPasskey` and `passkeySignIn` do the second step and passkeys as a person's devices do.
**Tier 3, `test/workerd/helpers.ts`:** `migrate`, `setupOwner`, `seedUser`, `seedMembership`, `signIn`, `request` (sends the app's own `Origin`), `createMailbox`, `mime` and `inbound` (a message for the `email` handler), `ageSessions` (make a session old instead of waiting), and `Browser`: a cookie-keeping client with a client address of its own, so the per-address sign-in limits do not couple tests. `enableApp`, `registerPasskey` and `passkeySignIn` do the second step and passkeys as a person's devices do. `test/workerd/sending-helpers.ts` has a send binding of the tests (`fakeSender`) and `letLeave`, which runs the mailbox's alarm until nothing is due; `test/workerd/rules-helpers.ts` has one mailbox with an owner, a sender, a reader and two people without a membership, `deliver` with an envelope sender of the test's choosing, and `audited`.

**Doubles, `test/helpers/`:** `authenticator.ts` (a software passkey that makes real attestations and signatures, and `totpCode`), `fake-ai.ts` (the model; no test ever calls a real one).

Expand Down
13 changes: 9 additions & 4 deletions .claude/skills/podbay-ui/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The app is a single-page app served as static assets. It shows strangers' mail i

## 3. How a mailbox behaves

The mail screens follow what a person expects from a first-class web mail client (the bar is the mail people know from Gmail and Google Workspace). The behaviour was studied on the live product and written down here in our own words; nothing of it is copied: no code, no text, no asset. These are decisions; `test/e2e/mailbox.spec.ts` holds each one, `test/e2e/writing.spec.ts` the ones about writing a message, `test/e2e/bulk.spec.ts` the ones about acting on many conversations and the order of a list, `test/e2e/original.spec.ts` the ones about the original of a message, `test/e2e/remembered.spec.ts` the ones about what is remembered beyond one browser: a person's choices and the addresses a mailbox has written to, `test/e2e/live.spec.ts` the ones about what an open tab learns without being asked, and `test/e2e/sending.spec.ts` the ones about what happens after Send.
The mail screens follow what a person expects from a first-class web mail client (the bar is the mail people know from Gmail and Google Workspace). The behaviour was studied on the live product and written down here in our own words; nothing of it is copied: no code, no text, no asset. These are decisions; `test/e2e/mailbox.spec.ts` holds each one, `test/e2e/writing.spec.ts` the ones about writing a message, `test/e2e/bulk.spec.ts` the ones about acting on many conversations and the order of a list, `test/e2e/original.spec.ts` the ones about the original of a message, `test/e2e/remembered.spec.ts` the ones about what is remembered beyond one browser: a person's choices and the addresses a mailbox has written to, `test/e2e/live.spec.ts` the ones about what an open tab learns without being asked, `test/e2e/sending.spec.ts` the ones about what happens after Send, and `test/e2e/rules.spec.ts` the ones about a mailbox's rules for incoming mail.

### The frame

Expand Down Expand Up @@ -98,7 +98,7 @@ A message is in one place and carries any number of labels. Places are fixed; ev
| A conversation is read **oldest first**. Its newest message and whatever is still unread are open, the rest are folded to one line each; the conversation's menu opens or folds all of them. A message deleted or reported from a conversation is no longer shown in it | `EmailPanel.tsx`, `ThreadMessage.tsx` |
| A conversation of five messages or more keeps its middle (between the first and the last two) behind one line that says how many are there | `EmailPanel.tsx` |
| Every message is as tall as it is: the conversation scrolls, never a message inside it. **Quoted text at the end of a reply is folded** behind "Show quoted text", inside the mail frame, and opens without script | `foldQuote` in `app/lib/mail-html.ts` (the renderer: load `podbay-security` before touching it) |
| **Each message has its own header and menu**: who wrote it (the name opens what can be done with the sender: write to them, find their mail, copy the address), "to" with the full details one click away, a star, Reply, and a menu: reply, reply to all, forward, delete this message, mark as unread, report spam, find messages from this sender, print, and then "Show original" and "Download message" for a message whose original is kept, or "Show headers" for one that has none. They act on that message, not on the conversation | `email-panel/MessageHeader.tsx`; `messageActions` in `EmailPanel.tsx` |
| **Each message has its own header and menu**: who wrote it (the name opens what can be done with the sender: write to them, find their mail, copy the address), "to" with the full details one click away, a star, Reply, and a menu: reply, reply to all, forward, delete this message, mark as unread, report spam, find messages from this sender, print, and then "Show original" and "Download message" for a message whose original is kept, or "Show headers" for one that has none. They act on that message, not on the conversation. For an owner of the mailbox the menu also has **"Block the sender"** (in the sender's own menu too), which asks first in the app's dialog and then sends that address's next mail to Spam, "Unblock the sender" in its place once the address is blocked, and **"Filter messages like this"**, which opens a new filter that starts with the sender (ADR-0008). Anyone else is offered neither: changing a mailbox's rules is the owner's, and the Worker decides it | `email-panel/MessageHeader.tsx`; `messageActions` in `EmailPanel.tsx`; `useSenderRules` in `app/hooks/useSenderRules.tsx` |
| **The original of a message** (ADR-0015) is the bytes it arrived as. "Show original" opens them as text, the first 256 KB, and says of how much: the header block, then what follows it. It is text and only text: text nodes in one preformatted block, never markup, never the mail frame, no link; a control character, and a character that changes the direction of text or takes no room, is drawn as a mark with its code point (`U+202E`), and the block is laid out left to right whatever it holds, so a line reads in the order of its bytes. "Download message" saves all of them as `message-YYYYMMDD-xxxxxxxx.eml`, a name the app makes; before that the app says, in its own dialog, that the file holds the whole message with every attachment and that another program opens it without Podbay's protections, and it names the attachments that can do harm. Only a received message has an original, and the Worker says which (`has_original`): a sent message and mail from before originals were kept offer "Show headers" instead, which says what the list is and why there is no original. What the platform recorded about SPF, DKIM and DMARC is written as the platform's statement, in a sentence, without a tick, a colour or a word of Podbay's own, and only under "Show original"; it is drawn only when the Worker gives it (`AUTHENTICATION_SHOWN` in `shared/original.ts`, off until the live check of the record is done) | `email-panel/OriginalMessage.tsx`; `markOriginal` and `authenticationWords` in `app/lib/original-text.ts`; `app/lib/original.ts`; `email-panel/EmailPanelDialogs.tsx` (the headers); `workers/routes/original.ts` |
| **A message Podbay could not read** (its structure, a text too large to keep, or a handler stopped twice) is in the inbox with the sender of the envelope, no subject and no text. Where its body would be, the app says that it could not read it and why, and offers the original to see and to save. It is never drawn in the mail frame | `email-panel/UnreadMessage.tsx`; `unparsed` in a message's answer |
| Mail from a list offers **Unsubscribe** beside the sender, when the message says how in `List-Unsubscribe`. The header is the sender's, so only an `https:` page without credentials, or a `mailto:` to one address, is taken. A page is opened by the person after the app says where it leads; a message is written for the person to send. Podbay contacts nobody by itself | `app/lib/unsubscribe.ts`, `leaveList` in `EmailPanel.tsx` |
Expand Down Expand Up @@ -138,7 +138,9 @@ A message is in one place and carries any number of labels. Places are fixed; ev
| **Notifications**, when asked for and allowed by the browser, announce mail that arrives while Podbay is open in a tab: the sender and the subject, nothing of the message, and nothing for what was already there. The mailbox says when mail arrived and the app then asks once for the top of the inbox; a move, a label or anything else that is told makes it ask for nothing. Only while nothing is telling the tab does it look every half minute. Nothing is pushed to a closed app | `NewMailNotifier.tsx`; its look has a query key of its own (`newMailKey` in `app/hooks/useLive.ts`) |
| Light or dark is the `data-mode` attribute on the document, set before the first paint; "as this device" follows the device while the app is open. A message keeps the colours its sender gave it | `showAppearance` in `useDisplay.ts` |
| What belongs to the mailbox is saved to it with its own button, by an owner; others see it and are told who can change it: the name mail is sent under, the signature, the assistant's prompt. Labels are managed here as well as in the rail. The Mailbox tab also says that the mailbox remembers the addresses it has written to, and lets an owner have it forget them all, after the app asked (ADR-0012, decision 20) | `MailboxDetails.tsx`, `SignatureSettings.tsx`, `AssistantSettings.tsx`, `LabelSettings.tsx` |
| A setting is never shown for something the Worker does not do. Forwarding and an automatic reply have a stored shape and no behaviour, so they have no screen | The roadmap, section 4 |
| **Filters and blocked senders** is a tab of its own (ADR-0008). A filter is made and changed in one dialog: what it looks for (the sender and a recipient, each "contains" or "is exactly"; the subject; words of the message; an attachment) and what it does (where the message goes, read, a star, labels). It is listed in words, one line for each condition and each action, each a whole message of the catalog; the list has the order the filters run in, and arrows move one up or down. The dialog says that a filter acts on mail that arrives and not on mail that is here. Blocked senders are listed under the filters, an address or "Everyone at" a domain, with a field to block one and Unblock on each. Everyone who reads the mailbox sees the tab; only an owner gets its buttons | `settings/FilterSettings.tsx`, `rules/FilterDialog.tsx`; the words of a rule are pure functions in `app/lib/rule-words.ts`; `app/queries/rules.ts`; the vocabulary and limits come from `shared/rules.ts` |
| **Automatic reply** is a tab of its own (ADR-0008): on or off, a beginning and an end in this device's time zone (what travels is the instant in UTC), a subject and a message. The tab says in plain words who is never answered. Saving it is a sensitive change: it goes through `useFreshProof()`, and the Worker decides. When the person who turned it on may no longer send from the mailbox, the tab says that nothing is being answered | `settings/AutoReplySettings.tsx`; `GET` and `PUT …/auto-reply` |
| A setting is never shown for something the Worker does not do. Forwarding has no behaviour, so it has no screen | The roadmap, section 4 |

### What changes elsewhere (ADR-0013)

Expand All @@ -147,7 +149,7 @@ The mailbox tells the open app that something changed, and nothing more. What ch
| Behaviour | How it is built |
|---|---|
| **New mail, a move, a label and read state appear by themselves**, in every open tab and for every member of a shared mailbox, within about a second and without a reload. Nothing on the screen says that there is a connection, and nothing is different when there is none except the wait | `useLive` in `app/hooks/useLive.ts`, mounted once by the frame (`app/routes/mailbox.tsx`): one connection for the mailbox on screen, open while the tab is, seen or not |
| The connection carries **four counters and no mail** (`delivery`, `mail`, `labels`, `settings`). The app compares each with the one it holds and reads again what that kind can have touched: lists, searches, the places' counts and the labels for `mail` and `labels`, the mailbox for `settings`, the notifier's look for `delivery`. Never draw anything from the message itself: it has nothing to draw | `shared/live.ts` is the schema, for the object and the app; `refetchMoved` in `useLive.ts` |
| The connection carries **four counters and no mail** (`delivery`, `mail`, `labels`, `settings`). The app compares each with the one it holds and reads again what that kind can have touched: lists, searches, the places' counts and the labels for `mail` and `labels`, the mailbox and its rules for `settings`, the notifier's look for `delivery`. Never draw anything from the message itself: it has nothing to draw | `shared/live.ts` is the schema, for the object and the app; `refetchMoved` in `useLive.ts` |
| **The connection is never trusted to be there.** A list asks by itself every half minute without one, as it always did, and every five minutes with one. A screen that needs to be current asks `useAskEvery(mailboxId)` for its interval and never assumes a signal | `useAskEvery` and `useLiveConnected` in `useLive.ts`; `routes/email-list.tsx` |
| When it drops the app tries again after a second, then double the wait up to a minute, each time by a random part less, and from the start once a connection held for ten seconds. It says `ping` once a minute and takes ten seconds without an answer for a connection that is gone. After about four minutes it opens a new one, through the guard again, and closes the old one when the new one has spoken, so a person never sees it. A burst of messages is one refetch at once and then at most one a second | `LiveConnection` in `app/lib/live.ts`: no React, the browser handed in, so every rule is a unit test (`test/unit/live.test.ts`) |
| A failed handshake tells a page nothing, so the app **does not guess why** and shows no error for it: the ordinary requests answer 401 or 404, and what the app does with those takes over. A message of a version the app does not know ends the connection for this tab, which goes on asking | `LiveConnection`; `readLiveMessage` in `shared/live.ts` |
Expand Down Expand Up @@ -212,6 +214,9 @@ The app speaks English and Turkish. Every word a person reads or hears goes thro
| A keyboard shortcut | `useShortcuts` in `app/hooks/useShortcuts.ts`; add it to `SHORTCUT_HELP` so the `?` dialog lists it |
| Sending a message from anywhere, with Undo and the mailbox's own word afterwards | `useSending` in `app/hooks/useSending.ts`. Never say "sent" yourself |
| Choosing a time | `SendLater.tsx` (a menu of times and a dialog with a date and time, each shown back) |
| A dialog with a form of several fields and a list that is saved whole | `rules/FilterDialog.tsx` |
| A setting of the mailbox whose save needs fresh proof | `settings/AutoReplySettings.tsx` |
| A thing said in words from data, a whole message for each part | `app/lib/rule-words.ts` |

## 6. A new screen

Expand Down
Loading
Loading