diff --git a/.claude/skills/podbay-security/SKILL.md b/.claude/skills/podbay-security/SKILL.md index b634b3e..734caa3 100644 --- a/.claude/skills/podbay-security/SKILL.md +++ b/.claude/skills/podbay-security/SKILL.md @@ -24,7 +24,7 @@ Find the paths you changed. A path may sit on more than one boundary. |---|---| | `workers/lib/inbound.ts`, `workers/lib/filenames.ts`, the `email` handler in `workers/app.ts`, `receiveEmail` in `workers/arrival.ts`, `workers/lib/original.ts` (the key of an original, the platform's `Authentication-Results` field), any use of the mail parser, `shared/log.ts` and any log call | B1 | | `app/lib/mail-html.ts`, `app/components/EmailIframe.tsx`, anything that puts message content in the DOM, the attachment route in `workers/index.ts`, `workers/lib/attachments.ts`, the original of a message: `workers/routes/original.ts`, `shared/original.ts`, `app/lib/original-text.ts`, `app/lib/original.ts`, `app/components/email-panel/OriginalMessage.tsx` | B2 | -| `workers/auth/options.ts`, `workers/auth/instance.ts`, `workers/routes/account.ts` (sign-in, setup), the origin check, the check of a WebSocket handshake (`upgradeRefusal`) and the session lookup in `workers/auth/middleware.ts`, the optional Access check in `workers/app.ts`, `migrations/0001_auth.sql`, cookies, response headers | B3 | +| `workers/auth/options.ts`, `workers/auth/used-codes.ts`, `workers/auth/instance.ts`, `workers/routes/account.ts` (sign-in, setup), the origin check, the check of a WebSocket handshake (`upgradeRefusal`) and the session lookup in `workers/auth/middleware.ts`, the optional Access check in `workers/app.ts`, `migrations/0001_auth.sql`, cookies, response headers | B3 | | `workers/auth/authorize.ts`, `workers/auth/route-table.ts`, `workers/auth/middleware.ts` (the guard), `workers/auth/store.ts`, `workers/routes/mailboxes.ts`, every route under `/api/v1/mailboxes/`, `workers/durableObject/`, the connection to the open app (`workers/routes/live.ts`, `workers/durableObject/live.ts`, `shared/live.ts`, `app/lib/live.ts`), `migrations/0002_index.sql`, any place that builds a Durable Object name or an R2 key | B4 | | `workers/agent/`, `workers/mcp/`, `workers/lib/tools.ts`, `workers/lib/ai.ts`, `workers/lib/features.ts`, the `/mcp` and `/agents` routes | B5 | | `workers/email-sender.ts`, `validateSender` in `workers/lib/email-helpers.ts`, `workers/routes/reply-forward.ts`, the send route in `workers/index.ts`, `workers/lib/outgoing.ts` and `outgoing-message.ts`, `workers/routes/sending.ts` (`unsend`, `reschedule`), in the mailbox object `leaving.ts` (the one function that lets mail leave), `submissions.ts` (the states and the handover), `alarm.ts` and `sending.ts` (the caps), `workers/auth/standing.ts`, `shared/sending.ts`, `scripts/checks/sender.ts` | B6 | @@ -77,15 +77,15 @@ Each boundary below has the same five lines: what crosses it, the invariant, the - **Crosses:** credentials, session cookies, invitation and recovery links and step-up proofs, from any browser. - **Invariant:** the design in [sign-in and access](../../../docs/auth-and-access.md). Invitation only. A new instance is closed until the guarded first-owner call. Sessions are server-side; cookies are host-only, `HttpOnly`, `Secure`, `SameSite=Lax`. Sensitive changes need fresh proof. Every authentication route is rate-limited and answers uniformly. Every state-changing request is checked against the app's own origin. -- **Code today:** Better Auth on D1 (`workers/auth/options.ts`, tables generated into `migrations/0001_auth.sql` and checked by `node scripts/auth-ddl.ts --check`). Password sign-in with a 12-character minimum; rate limits counted in the database. Accounts cannot be created over HTTP: the sign-up endpoint is refused, and accounts are made on the server by the guarded first-owner call (`POST /api/setup/owner`, needs the `SETUP_TOKEN` secret, works once, compared in constant time). An account without an instance role is not admitted. Every request that changes state must carry the app's own `Origin` (`sameOrigin` in `workers/auth/middleware.ts`). Cloudflare Access is an optional outer layer; a half-configured Access refuses to run. **Second step and passkeys** (Better Auth's two-factor plugin and `@better-auth/passkey`, tables in `migrations/0005_second_step.sql`): an authenticator app with recovery codes, enabled with the password and a first code, secrets and codes stored encrypted; `workers/auth/options.ts` refuses trusted devices (`trustDevice`), codes by mail or text message, and any method but the app. A passkey is bound to the request's hostname, needs user verification and a resident key, and is a complete sign-in. **Fresh proof (step-up)** has one definition (`workers/auth/fresh.ts`): the session signed in within `FRESH_SECONDS` (ten minutes), and signing in again replaces the session (`afterAuthEndpoint` deletes the one the browser held). Routes marked `fresh` in the route table are checked last in the guard, on the session read from the database; Better Auth's own endpoints that change how a person signs in are held to it in `beforeAuthEndpoint` (`FRESH_AUTH_PATHS`), and registering a passkey by the plugin itself with the same `freshAge`. Sign-in attempts are counted per `cf-connecting-ip`. **Recovery** (`workers/auth/recovery.ts`, `workers/routes/recovery.ts`, table in `migrations/0006_recoveries.sql`): a link is issued by someone else, never for oneself (`mayIssueRecovery`: an owner for anyone, an administrator for members only), with fresh proof; the operator issues one for an owner with `SETUP_TOKEN`, compared in constant time (`POST /api/setup/recovery`). A link is 256 random bits, stored as a digest, good for a day, and a new one replaces the old. Redeeming it is one D1 batch whose later statements run only if the first marked the link used: new password hash, every session deleted, authenticator app and passkeys deleted, program keys revoked, audit row. It signs nobody in and never shows an old credential. **A person's choices** (ADR-0012; `migrations/0007_user_choices.sql`, `workers/auth/choices.ts`, `workers/routes/choices.ts`): `GET` and `PUT /api/v1/me/choices` have the right `session` and take the person from the session only; no id is in the path, the query or the body, so nothing points at someone else. The body is read up to 4 KiB and no further, then held to the strict schema (`shared/choices-schema.ts`): a key or a value it does not know refuses the whole change. The merge is one statement. The Worker stores the choices and decides nothing by them: not access, not what a list returns, not what is sent. A recovery link leaves them; the row goes with the account. **A route that opens a WebSocket** (ADR-0013) has a mark of its own in the route table, `upgrade`, and the guard is stricter for it than for a read, in this order: the request must be a WebSocket upgrade (426); its `Origin` must be the app's own, so one that is missing, `null`, another site's or a sibling host's is refused (403) before a session is looked for, with one answer whoever asks (`upgradeRefusal`: a handshake is a GET, a browser sends the cookie with it from any page of the same site, and a program has no `Origin` and so no way in); and the session is read from the database, as for a route marked `fresh`, so one that was ended a moment ago opens nothing. The proof is the session cookie; nothing in the address is ever read as one. What is opened is good for five minutes: the mailbox object keeps the time the guard allowed it and closes an older connection before it sends anything, and the app comes back through the guard after about four. The object does not know sessions, so a session that ends stops being told at five minutes at the latest and can open nothing new; the app closes its connections before it signs out and the server does not rely on that. **Mail that outlives a session** (ADR-0016): someone who held a session for a short while can schedule mail up to a year ahead. It is seen in Scheduled by everyone who reads the mailbox until it has left, and the right of whoever sent it is asked again when it leaves, by `authorize` (`workers/auth/standing.ts`): a membership that ended, a role lowered to reader and an account recovered since the press each stop it, and it comes back to Drafts with the reason. -- **Proof today:** `test/workerd/leaving.test.ts` (a message scheduled, then the membership removed, the role lowered or the account recovered: it does not leave; a recovery used before the press does not stop a message). `test/workerd/sessions.test.ts` (a person lists only their own sessions and only with fresh proof; ending one signs that browser out and no other; nobody ends a session that is not theirs; a password change needs the current password, ends every other session and retires the old password) and `account.spec.ts` in the browser. `test/workerd/access.test.ts`: a new instance answers 401 everywhere; the first-owner call is refused without the token, with a weak password and from another origin, and works once; HTTP sign-up is refused and creates no row; a wrong password and a forged cookie are refused; the session cookie is `HttpOnly`, `Secure`, `SameSite=Lax`; a cross-origin or origin-less mutation is refused. `test/workerd/second-step.test.ts`: the app is not in force before its first code; then a password alone gives no session; a wrong code, a code without the password step and a reused recovery code are refused; `trustDevice` is refused and the same browser is asked again; codes by mail are refused; guesses from one address are limited; the secret and the recovery codes are not readable in D1. A passkey registers only with a fresh session, signs in by itself (also for a person with an app), and is refused without user verification, for another origin or site id, when unknown, and when an answer is replayed. An eleven-minute-old session still reads and does ordinary work but is refused every sensitive change, with nothing changed and nothing revealed about a mailbox it may not manage; signing in again gives it back and leaves no older session. `test/unit/fresh.test.ts`: the window, the exact list of fresh routes, and that every Better Auth path named in the rules is an endpoint of the installed version. `test/workerd/recovery.test.ts`: who may issue for whom, never for oneself, never stale, never to a member or without a session; the token is not in D1 or the audit log; a person with a session, a passkey, an app and a key ends with the new password alone (old password refused, no code asked, passkey refused, key revoked, sessions gone); a link works once even for two requests at once; a short password does not use it up; unknown, replaced and expired links answer alike; the operator call needs the setup token and the app's origin, and serves owners only. `test/unit/recovery.test.ts`: the issue matrix. **A person's choices** (`test/workerd/choices.test.ts`): an owner, an administrator and a member each read and change their own document and no other; the route table has the two routes and neither has a parameter; a person named in the query is not looked at and one named in the body refuses the request; the list of people, a person's own account and the registry carry no choices; a request without a session, from another origin or with a program key is refused; an unknown key, an unknown value, a choice of the device and a body over the limit are refused and change nothing; two changes at once to different choices both stay; an unknown stored key stays and is not given on; a document of a later version is not written; the table comes with the database of the release before it and the row goes with the account. `test/unit/choices.test.ts` holds the schema and that only the store and the route name the table. **The handshake** (`test/workerd/live.test.ts`): the table has exactly one route marked `upgrade`; a request that is not an upgrade, or claims another protocol, is 426 with one answer for a member, a stranger and nobody; another site, a sibling host, the same host over another scheme, `null` and no origin are each 403 with one answer whether a member's session, a stranger's or none is sent; `upgradeRefusal` by itself for a port, a trailing slash and the order of its two refusals; a session deleted from the database is refused the connection while an ordinary read still passes on the cookie's copy; a session token in the address or as a bearer is 401; a connection allowed five minutes ago is closed with nothing sent on it by the next write and by the next connection, one a minute short is told, and a time ahead of the object's clock is not kept. Each of these was seen to fail with its control taken out. `test/unit/live.test.ts`: the app opens a new connection before five minutes and stops everything when told to; `pnpm e2e` `live.spec.ts`: the handshake passes from the app's own page under the real headers. -- **Open:** a session that was ended is told for up to five minutes more on a connection it opened before (ADR-0013, decision 13); no self-service reset (a recovery address outside Podbay and reset links by mail); the setup token is a standing owner-recovery credential unless the deployer removes it; Podbay's own public routes are not rate-limited; nobody is required to have a second step; a code can be reused within its 30 seconds; passkeys are tested with Chrome's virtual authenticator, not with a physical device; changing a password in the app; the app's own response headers (content policy, `frame-ancestors`, HSTS); session listing and revocation in the UI. Do not add a second way to create an account. +- **Code today:** Better Auth on D1 (`workers/auth/options.ts`, tables generated into `migrations/0001_auth.sql` and checked by `node scripts/auth-ddl.ts --check`). Password sign-in with a 12-character minimum; rate limits counted in the database. Accounts cannot be created over HTTP: the sign-up endpoint is refused, and accounts are made on the server by the guarded first-owner call (`POST /api/setup/owner`, needs the `SETUP_TOKEN` secret, works once, compared in constant time). An account without an instance role is not admitted. Every request that changes state must carry the app's own `Origin` (`sameOrigin` in `workers/auth/middleware.ts`). Cloudflare Access is an optional outer layer; a half-configured Access refuses to run. **Second step and passkeys** (Better Auth's two-factor plugin and `@better-auth/passkey`, tables in `migrations/0005_second_step.sql`): an authenticator app with recovery codes, enabled with the password and a first code, secrets and codes stored encrypted; `workers/auth/options.ts` refuses trusted devices (`trustDevice`), codes by mail or text message, and any method but the app. A passkey is bound to the request's hostname, needs user verification and a resident key, and is a complete sign-in. **A code from the app is used once** (`workers/auth/used-codes.ts`, the last step of `beforeAuthEndpoint`): before Better Auth sees a code it is claimed for the person it is typed for, as a row of Better Auth's `verification` table whose primary key is an HMAC of the person and the code under the instance secret, kept for two minutes; a second request with the same code fails to write that row, in whatever isolate, and is answered as a wrong code. **Fresh proof (step-up)** has one definition (`workers/auth/fresh.ts`): the session signed in within `FRESH_SECONDS` (ten minutes), and signing in again replaces the session (`afterAuthEndpoint` deletes the one the browser held). Routes marked `fresh` in the route table are checked last in the guard, on the session read from the database; a route marked `sensitive`, where only some requests need fresh proof (saving a mailbox's settings, which needs it when forwarding changes), has its session read from the database as well, and `test/unit/fresh.test.ts` holds that only its code reads the flag; Better Auth's own endpoints that change how a person signs in are held to it in `beforeAuthEndpoint` (`FRESH_AUTH_PATHS`), and registering a passkey by the plugin itself with the same `freshAge`. Sign-in attempts are counted per `cf-connecting-ip`. **Recovery** (`workers/auth/recovery.ts`, `workers/routes/recovery.ts`, table in `migrations/0006_recoveries.sql`): a link is issued by someone else, never for oneself (`mayIssueRecovery`: an owner for anyone, an administrator for members only), with fresh proof; the operator issues one for an owner with `SETUP_TOKEN`, compared in constant time (`POST /api/setup/recovery`). A link is 256 random bits, stored as a digest, good for a day, and a new one replaces the old. Redeeming it is one D1 batch whose later statements run only if the first marked the link used: new password hash, every session deleted, authenticator app and passkeys deleted, program keys revoked, audit row. It signs nobody in and never shows an old credential. **A person's choices** (ADR-0012; `migrations/0007_user_choices.sql`, `workers/auth/choices.ts`, `workers/routes/choices.ts`): `GET` and `PUT /api/v1/me/choices` have the right `session` and take the person from the session only; no id is in the path, the query or the body, so nothing points at someone else. The body is read up to 4 KiB and no further, then held to the strict schema (`shared/choices-schema.ts`): a key or a value it does not know refuses the whole change. The merge is one statement. The Worker stores the choices and decides nothing by them: not access, not what a list returns, not what is sent. A recovery link leaves them; the row goes with the account. **A route that opens a WebSocket** (ADR-0013) has a mark of its own in the route table, `upgrade`, and the guard is stricter for it than for a read, in this order: the request must be a WebSocket upgrade (426); its `Origin` must be the app's own, so one that is missing, `null`, another site's or a sibling host's is refused (403) before a session is looked for, with one answer whoever asks (`upgradeRefusal`: a handshake is a GET, a browser sends the cookie with it from any page of the same site, and a program has no `Origin` and so no way in); and the session is read from the database, as for a route marked `fresh`, so one that was ended a moment ago opens nothing. The proof is the session cookie; nothing in the address is ever read as one. What is opened is good for five minutes: the mailbox object keeps the time the guard allowed it and closes an older connection before it sends anything, and the app comes back through the guard after about four. The object does not know sessions, so a session that ends stops being told at five minutes at the latest and can open nothing new; the app closes its connections before it signs out and the server does not rely on that. **Mail that outlives a session** (ADR-0016): someone who held a session for a short while can schedule mail up to a year ahead. It is seen in Scheduled by everyone who reads the mailbox until it has left, and the right of whoever sent it is asked again when it leaves, by `authorize` (`workers/auth/standing.ts`): a membership that ended, a role lowered to reader and an account recovered since the press each stop it, and it comes back to Drafts with the reason. +- **Proof today:** `test/workerd/leaving.test.ts` (a message scheduled, then the membership removed, the role lowered or the account recovered: it does not leave; a recovery used before the press does not stop a message). `test/workerd/sessions.test.ts` (a person lists only their own sessions and only with fresh proof; ending one signs that browser out and no other; nobody ends a session that is not theirs; a password change needs the current password, ends every other session and retires the old password) and `account.spec.ts` in the browser. `test/workerd/access.test.ts`: a new instance answers 401 everywhere; the first-owner call is refused without the token, with a weak password and from another origin, and works once; HTTP sign-up is refused and creates no row; a wrong password and a forged cookie are refused; the session cookie is `HttpOnly`, `Secure`, `SameSite=Lax`; a cross-origin or origin-less mutation is refused. `test/workerd/second-step.test.ts`: the app is not in force before its first code; then a password alone gives no session; a wrong code, a code without the password step and a reused recovery code are refused; `trustDevice` is refused and the same browser is asked again; codes by mail are refused; guesses from one address are limited; the secret and the recovery codes are not readable in D1. A code from the app is refused the second time: the one that turned the app on, one that signed in another browser, and one given by two sign-ins at once let in exactly one, each refusal byte for byte a wrong code's answer, and the claim holds no code. A passkey registers only with a fresh session, signs in by itself (also for a person with an app), and is refused without user verification, for another origin or site id, when unknown, and when an answer is replayed. An eleven-minute-old session still reads and does ordinary work but is refused every sensitive change, with nothing changed and nothing revealed about a mailbox it may not manage; forwarding is refused to a session the database calls old while its cookie's copy calls it new, and to one ended a moment ago whose copy is still in the cookie; signing in again gives it back and leaves no older session. `test/unit/fresh.test.ts`: the window, the exact list of fresh routes, and that every Better Auth path named in the rules is an endpoint of the installed version. `test/workerd/recovery.test.ts`: who may issue for whom, never for oneself, never stale, never to a member or without a session; the token is not in D1 or the audit log; a person with a session, a passkey, an app and a key ends with the new password alone (old password refused, no code asked, passkey refused, key revoked, sessions gone); a link works once even for two requests at once; a short password does not use it up; unknown, replaced and expired links answer alike; the operator call needs the setup token and the app's origin, and serves owners only. `test/unit/recovery.test.ts`: the issue matrix. **A person's choices** (`test/workerd/choices.test.ts`): an owner, an administrator and a member each read and change their own document and no other; the route table has the two routes and neither has a parameter; a person named in the query is not looked at and one named in the body refuses the request; the list of people, a person's own account and the registry carry no choices; a request without a session, from another origin or with a program key is refused; an unknown key, an unknown value, a choice of the device and a body over the limit are refused and change nothing; two changes at once to different choices both stay; an unknown stored key stays and is not given on; a document of a later version is not written; the table comes with the database of the release before it and the row goes with the account. `test/unit/choices.test.ts` holds the schema and that only the store and the route name the table. **The handshake** (`test/workerd/live.test.ts`): the table has exactly one route marked `upgrade`; a request that is not an upgrade, or claims another protocol, is 426 with one answer for a member, a stranger and nobody; another site, a sibling host, the same host over another scheme, `null` and no origin are each 403 with one answer whether a member's session, a stranger's or none is sent; `upgradeRefusal` by itself for a port, a trailing slash and the order of its two refusals; a session deleted from the database is refused the connection while an ordinary read still passes on the cookie's copy; a session token in the address or as a bearer is 401; a connection allowed five minutes ago is closed with nothing sent on it by the next write and by the next connection, one a minute short is told, and a time ahead of the object's clock is not kept. Each of these was seen to fail with its control taken out. `test/unit/live.test.ts`: the app opens a new connection before five minutes and stops everything when told to; `pnpm e2e` `live.spec.ts`: the handshake passes from the app's own page under the real headers. +- **Open:** a session that was ended is told for up to five minutes more on a connection it opened before (ADR-0013, decision 13); no self-service reset (a recovery address outside Podbay and reset links by mail); the setup token is a standing owner-recovery credential unless the deployer removes it; Podbay's own public routes are not rate-limited; nobody is required to have a second step; passkeys are tested with Chrome's virtual authenticator, not with a physical device; changing a password in the app; the app's own response headers (content policy, `frame-ancestors`, HSTS); session listing and revocation in the UI. Do not add a second way to create an account. ### B4. Per-mailbox authorisation - **Crosses:** a mailbox, message or attachment id in a request, and the identity of the caller. - **Invariant:** deny by default. One `authorize(actor, action, resource)` decides for every route, tool and connection, from one table. A non-member gets "not found". **Managing is not reading:** an owner or administrator without a membership cannot open a mailbox, and granting themselves one needs step-up, is audited and is visible to the mailbox's owners. An id from a request is resolved to an opaque id before it touches storage. Deleting a message or a mailbox removes its rows, its Durable Object data and its R2 objects. -- **Code today:** `authorize` in `workers/auth/authorize.ts` decides; `ROUTE_TABLE` in `workers/auth/route-table.ts` names the right of every API route; the guard in `workers/auth/middleware.ts` runs in front of all of `/api/*`, refuses a route that is not in the table, resolves the mailbox through the D1 index with the caller's membership, and names the Durable Object after the address stored in the index, never after the request. A non-member gets 404, whatever their instance role, with one exception that `authorize` names: `mailbox.members.read` and `mailbox.members.manage` are also allowed to an owner or administrator of the instance without a membership. The guard looks the mailbox up with the caller's membership or none (`mailboxFor`), sets the storage stub only when there is a membership, and lets `authorize` decide; so a manager reaches the member routes (`workers/routes/people.ts`) and the registry (`GET /api/v1/registry/mailboxes`: address, owners, member count) and nothing else. Every member change needs fresh proof and is recorded with whose membership, which role and in which capacity it was made (`membershipDetail`: `as: owner` or `as: manager`, `self:` for one's own); `memberHistory` reads that record back for the mailbox's owners, including a manager who added and removed themselves. A mailbox always keeps an owner. Deleting a mailbox purges its Durable Object and its attachments (`purge` in `workers/durableObject/index.ts`). The agent connection checks a session and the right to change mail in that mailbox (`mailboxDecision`). **Many conversations at once** (ADR-0014; `workers/routes/bulk.ts`, `workers/durableObject/deeds.ts` and `deed-steps.ts`): three routes, each `mailbox.write` in the route table. The request is parsed by one schema the app takes its types from (`shared/bulk.ts`): it names no target but Inbox, Archive, Spam and Trash and no change but a move, read, a star and labels, so nothing in it deletes for good or sends. A filter is the search route's own conditions (`buildSearchConditions`) and is only counted by the request that names it; acting is a second call that names the deed, whose id is opaque and is looked up in the database of the mailbox the guard picked. What a deed changed is kept for an hour as ids, places and marks, never content, and goes row by row with a message that is deleted for good. A filter deed is written to the audit log when it starts and when it is undone (`mailbox.bulk`, `mailbox.bulk_undone`) with who, which mailbox, which change and how many, never the filter. **The original of a message** (ADR-0015): both routes are `mailbox.read` in the route table. The message id only looks a row up in the database of the mailbox the guard picked (`originalOf` in `workers/durableObject/originals.ts`), and the key of the object comes from that row and from nowhere else: no code builds the key of an original. `raw_key` and `auth_results` never leave the mailbox object in an answer about a message (`shownMessage`), which says `has_original`, `raw_size` and `unparsed`. **Deletion** (rule S13): objects go before rows. One function deletes a message (`deleteMessage` in `workers/lib/messages.ts`: its files, its original, then its rows); emptying a place names a batch and its objects, deletes the objects, then the rows of that batch (`workers/durableObject/emptying.ts`); deleting a mailbox reads the keys of every file, every original and every arrival (`allKeys`), deletes the objects a thousand at a time, and only then empties the mailbox object. A failure leaves rows that can be deleted again, never an object no row names. **Known addresses** (ADR-0012; `workers/routes/known-addresses.ts`): completing an address is part of writing, so `GET …/known-addresses?q=` and forgetting one need `mailbox.write`, and forgetting them all `mailbox.manage`, which is audited by the mailbox and a number, never an address. The query is 1 to 64 characters, compared with `substr` and never put into a pattern; the answer is at most 8 entries of id, address and name, with no paging, total, count or date. The addresses are in the mailbox's own database, so they are deleted with it. **A person's choices** are not a mailbox's and not a manager's: see B3. **The mailbox tells the open app** (ADR-0013; `workers/routes/live.ts`, `workers/durableObject/live.ts`, `shared/live.ts`): being told that a mailbox changed is a way of reading it, so `GET …/live` is `mailbox.read` in the route table: a reader listens, and someone without a membership is told 404 whatever their instance role. **Nothing on the connection is mail:** the object sends one shape, a version and four counters, built by `liveMessage` from the list of kinds and from nothing else, at most 256 bytes; what changed is read through the ordinary routes, each authorised as before. The signal is raised by the write itself: `watch` wraps every method of the mailbox object where the class is defined, asks SQLite how many rows changed, and moves the counters the method is about (`ABOUT`; mail when it says nothing), so no caller can forget it or raise it without writing. **The object is told who by the Worker:** the route hands it a request it builds (`liveRequest`), with the person's id and the time the guard allowed it and nothing of the browser's; the object keeps the id as the connection's tag and the time as its attachment, and no session and no role. **A right that ends, ends here too:** the routes that remove a member or change a role close that person's connections in the same request, after the index is written (`closeLiveOf`, also for someone who manages the instance and has no membership: the one call reads nothing); deleting a mailbox closes them all (`purge`); and whatever the Worker did not know about ends at five minutes (B3). The app says `ping`, which the platform answers; any other message closes the connection (1008). Eight connections for a person in a mailbox, two hundred for a mailbox. Logs name the object's id and the account's id, never a message. **Outgoing mail** (ADR-0016; `workers/routes/sending.ts`, `workers/durableObject/submissions.ts`): `POST …/emails/:id/unsend` and `…/reschedule` are `mailbox.send` in the route table, like the three send routes; seeing Scheduled is `mailbox.read`. The id only looks a row up in the database of the mailbox the guard picked. **A message enters and leaves the place Scheduled only by being sent, taken back or let go:** the mailbox object's own methods refuse a waiting message (`inScheduled`) wherever one is moved, deleted, marked or labelled, and refuse Scheduled as a target, so no route and no tool can do it by another way; a deed on many conversations that names one is refused whole, and one on a conversation or a search passes over it. Deleting a mailbox takes its alarm off and deletes every row, the ones that wait among them, so nothing is sent afterwards. +- **Code today:** `authorize` in `workers/auth/authorize.ts` decides; `ROUTE_TABLE` in `workers/auth/route-table.ts` names the right of every API route; the guard in `workers/auth/middleware.ts` runs in front of all of `/api/*`, refuses a route that is not in the table, resolves the mailbox through the D1 index with the caller's membership, and names the Durable Object after the address stored in the index, never after the request. A non-member gets 404, whatever their instance role, with one exception that `authorize` names: `mailbox.members.read` and `mailbox.members.manage` are also allowed to an owner or administrator of the instance without a membership. The guard looks the mailbox up with the caller's membership or none (`mailboxFor`), sets the storage stub only when there is a membership, and lets `authorize` decide; so a manager reaches the member routes (`workers/routes/people.ts`) and the registry (`GET /api/v1/registry/mailboxes`: address, owners, member count) and nothing else. Every member change needs fresh proof and is recorded with whose membership, which role and in which capacity it was made (`membershipDetail`: `as: owner` or `as: manager`, `self:` for one's own); `memberHistory` reads that record back for the mailbox's owners, including a manager who added and removed themselves. A mailbox always keeps an owner. Deleting a mailbox purges its Durable Object and its attachments (`purge` in `workers/durableObject/index.ts`). The agent connection checks a session and the right to change mail in that mailbox (`mailboxDecision`). **One message moved** (`POST …/emails/:id/move`, `moveEmail` in the mailbox object): Sent is never a target, Scheduled neither a source nor a target, and Drafts takes only a message the mailbox wrote and that never left (`writtenHere` in `workers/durableObject/drafts.ts`: no Message-ID, header list, original or `unparsed`), which is how the app undoes deleting a draft; `test/workerd/move.test.ts`. **Many conversations at once** (ADR-0014; `workers/routes/bulk.ts`, `workers/durableObject/deeds.ts` and `deed-steps.ts`): three routes, each `mailbox.write` in the route table. The request is parsed by one schema the app takes its types from (`shared/bulk.ts`): it names no target but Inbox, Archive, Spam and Trash and no change but a move, read, a star and labels, so nothing in it deletes for good or sends. A filter is the search route's own conditions (`buildSearchConditions`) and is only counted by the request that names it; acting is a second call that names the deed, whose id is opaque and is looked up in the database of the mailbox the guard picked. What a deed changed is kept for an hour as ids, places and marks, never content, and goes row by row with a message that is deleted for good. A filter deed is written to the audit log when it starts and when it is undone (`mailbox.bulk`, `mailbox.bulk_undone`) with who, which mailbox, which change and how many, never the filter. **The original of a message** (ADR-0015): both routes are `mailbox.read` in the route table. The message id only looks a row up in the database of the mailbox the guard picked (`originalOf` in `workers/durableObject/originals.ts`), and the key of the object comes from that row and from nowhere else: no code builds the key of an original. `raw_key` and `auth_results` never leave the mailbox object in an answer about a message (`shownMessage`), which says `has_original`, `raw_size` and `unparsed`. **Deletion** (rule S13): objects go before rows. One function deletes a message (`deleteMessage` in `workers/lib/messages.ts`: its files, its original, then its rows); emptying a place names a batch and its objects, deletes the objects, then the rows of that batch (`workers/durableObject/emptying.ts`); deleting a mailbox reads the keys of every file, every original and every arrival (`allKeys`), deletes the objects a thousand at a time, and only then empties the mailbox object. A failure leaves rows that can be deleted again, never an object no row names. **Known addresses** (ADR-0012; `workers/routes/known-addresses.ts`): completing an address is part of writing, so `GET …/known-addresses?q=` and forgetting one need `mailbox.write`, and forgetting them all `mailbox.manage`, which is audited by the mailbox and a number, never an address. The query is 1 to 64 characters, compared with `substr` and never put into a pattern; the answer is at most 8 entries of id, address and name, with no paging, total, count or date. The addresses are in the mailbox's own database, so they are deleted with it. **A person's choices** are not a mailbox's and not a manager's: see B3. **The mailbox tells the open app** (ADR-0013; `workers/routes/live.ts`, `workers/durableObject/live.ts`, `shared/live.ts`): being told that a mailbox changed is a way of reading it, so `GET …/live` is `mailbox.read` in the route table: a reader listens, and someone without a membership is told 404 whatever their instance role. **Nothing on the connection is mail:** the object sends one shape, a version and four counters, built by `liveMessage` from the list of kinds and from nothing else, at most 256 bytes; what changed is read through the ordinary routes, each authorised as before. The signal is raised by the write itself: `watch` wraps every method of the mailbox object where the class is defined, asks SQLite how many rows changed, and moves the counters the method is about (`ABOUT`; mail when it says nothing), so no caller can forget it or raise it without writing. **The object is told who by the Worker:** the route hands it a request it builds (`liveRequest`), with the person's id and the time the guard allowed it and nothing of the browser's; the object keeps the id as the connection's tag and the time as its attachment, and no session and no role. **A right that ends, ends here too:** the routes that remove a member or change a role close that person's connections in the same request, after the index is written (`closeLiveOf`, also for someone who manages the instance and has no membership: the one call reads nothing); deleting a mailbox closes them all (`purge`); and whatever the Worker did not know about ends at five minutes (B3). The app says `ping`, which the platform answers; any other message closes the connection (1008). Eight connections for a person in a mailbox, two hundred for a mailbox. Logs name the object's id and the account's id, never a message. **Outgoing mail** (ADR-0016; `workers/routes/sending.ts`, `workers/durableObject/submissions.ts`): `POST …/emails/:id/unsend` and `…/reschedule` are `mailbox.send` in the route table, like the three send routes; seeing Scheduled is `mailbox.read`. The id only looks a row up in the database of the mailbox the guard picked. **A message enters and leaves the place Scheduled only by being sent, taken back or let go:** the mailbox object's own methods refuse a waiting message (`inScheduled`) wherever one is moved, deleted, marked or labelled, and refuse Scheduled as a target, so no route and no tool can do it by another way; a deed on many conversations that names one is refused whole, and one on a conversation or a search passes over it. Deleting a mailbox takes its alarm off and deletes every row, the ones that wait among them, so nothing is sent afterwards. - **Proof today:** `test/workerd/sending-routes.test.ts` (outgoing mail: an owner and a sender send, take back and give a new time; a reader sees Scheduled and is refused all of it; someone without a membership, whatever they manage, gets 404, nobody is served without a session or from another origin; a waiting message of another mailbox is 404; every route that changes mail refuses a waiting message with 409 `SCHEDULED` and changes nothing; nothing can be moved into Scheduled; after a mailbox is deleted no row, no object and no alarm is left and the send binding was never called); `test/workerd/original-routes.test.ts` and `test/workerd/original.test.ts` (the original: a reader is served and a non-member gets 404 on both routes, 401 without a session; a message id of another mailbox the caller is also a member of is 404; no answer of the message, list, thread, search and original routes contains `raw_key`, `auth_results` or the key itself; a sent message, a draft and old mail answer `NO_ORIGINAL`, a row whose object is gone `ORIGINAL_MISSING`; after deleting a message for good, emptying Trash and deleting the mailbox the bucket holds nothing of it, an arrival's object included; a bucket that fails leaves the rows; the migration is run from the release before it and rewrites nothing); `test/workerd/bulk.test.ts` (acting on many conversations: a reader is refused and a non-member told nothing on all three routes; a message, a label and a deed of another mailbox do not exist here; over a limit, an empty filter, both or neither scope, an unknown change, and Sent or Drafts as a target are refused with nothing changed; a filter request changes nothing, and a deed is not run without it, later than ten minutes, or after its scope grew; mail stored after the asking is never taken; undo is refused after the hour and never undoes a later change; a deleted message leaves no row in the record; the audit rows carry no word of the search) and `test/unit/bulk.test.ts` (the schema and its limits); `test/workerd/emptying.test.ts` (emptying takes Trash and Spam only, refuses a reader and tells a non-member nothing, and leaves no row or object of what was there); `test/unit/authorize.test.ts` (the whole rights matrix, the table's shape) and `test/workerd/access.test.ts`: every registered route is in the table and the table names no missing route; each mailbox route answers 404 to a signed-in non-member and to an administrator without a membership, 401 without a session, 403 to a reader where it changes anything, 403 to a sender where it manages; a crafted address is 404; an administrator can create a mailbox for someone else and then cannot open it; deletion removes mail, attachments, the index row and memberships, and a new mailbox at the same address starts empty. `test/workerd/members.test.ts`: an owner adds by address, changes and removes; a non-owner member sees the list and changes nothing; a non-member gets 404 on every member route; an administrator without a membership sees members, history and the registry but gets 404 on mail, settings, folders and deletion; their self-grant opens the mailbox and is on the record, which stays after they leave; the last owner cannot be removed or demoted by anyone; every change is refused without fresh proof; the audit rows carry the capacity. `test/workerd/access.test.ts` pins that the member routes are the only mailbox routes an administrator without a membership passes. **Labels** (ADR-0007): `test/workerd/labels.test.ts`: a reader sees labels and changes none, someone without a membership is told nothing, a label of another mailbox does not exist here, a label that is asked for and is not one finds nothing, deleting a label deletes no mail, deleting a message leaves no label row, and nobody makes, renames or removes a place; `test/unit/labels.test.ts` (ids, names). `test/workerd/known-addresses.test.ts` (known addresses: 404 on all three routes to someone without a membership and to an administrator without one, 403 to a reader, 401 without a session, 403 from another origin; a sender completes and forgets one and is refused forgetting all; an owner forgets all, on the record without an address; another mailbox's addresses never appear and its ids are nothing here; what is typed is never a pattern, also when it is longer than a pattern may be; no empty and no over-long query; never more than 8, and no way to the rest; forgetting after two years and above 5,000; deleting a sent message forgets nothing; deleting the mailbox leaves no row; the migration is run from the release before it and reads nothing back). `test/workerd/choices.test.ts` (managing is not reading: no route gives an owner or an administrator another person's choices). **The connection** (`test/workerd/live.test.ts`): an owner, a sender and a reader listen; someone without a membership and an administrator without one get 404, as does a mailbox that is not there or a crafted name; 401 without a session (and the generic loops of `test/workerd/access.test.ts` now ask it as a handshake). Removing a member closes that person's connections and no other's by the time the request has answered, and what happens next is told to the owner only; a changed role closes them and the person comes back through the guard; a refused change closes nothing; an administrator without a membership who removes a member closes them too and still cannot listen; deleting the mailbox closes every connection. After the object was put out of memory a connection is found by its tag, belongs to the same person, and is told once and closed as before. The ninth connection of a person closes their oldest; the two hundred and first is 503 and closes nobody; the object refuses a request that is not the Worker's handshake; `ping` is answered and anything else, bytes included, is closed with 1008 and tells nobody. The log lines carry opaque ids and no address, counter or word. **What is told** (`test/workerd/live-signal.test.ts`): marked content fed through every kind of write appears in no message of either tab, every message is the one shape under 256 bytes, no state is sent twice, each counter moves for exactly what it should and none for a read or a refusal; the test lists the object's methods, fails for one that is neither a known read nor known by what it is about, calls each read and fails if it changes a row, and shows a method written without knowledge of the signal raising it; the migration is run from the release before it. `pnpm e2e` `live.spec.ts`: in a real browser the frames are counters only. - **Open:** a session that ended is told for up to five minutes on a connection opened before, and the object cannot tell (B3); nothing limits how often one person opens the connection beyond the limits of a mailbox; opaque storage ids (the Durable Object and attachment keys are still named after the address and the message id; the key of an original is random and read from its row); mail that arrives while its mailbox is being deleted can still write into the emptied mailbox object; a mailbox's owners are not notified when someone who manages the instance changes its members, they see it when they look; the record is read from audit rows by address; the assistant's chat history is not purged with the mailbox. A member can walk the alphabet through the completion, a few answers at a time: it shows nothing Sent does not, except an address whose messages were deleted for good, and the route is not rate-limited (ADR-0012, accepted there). diff --git a/AGENTS.md b/AGENTS.md index 99e7f2a..6edec4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,7 @@ curl -X POST 'http://localhost:5173/cdn-cgi/local/email?from=a@sender.test&to=he ## Layout -- `workers/` — the Worker: `app.ts` (entry, `fetch` and `email`), `index.ts` (API routes), `arrival.ts` (inbound mail: the original kept, then parsed and filed), `auth/` (Better Auth configuration, `authorize.ts`, the route table, the guard, the D1 index store, invitations and members, `keys.ts` for program keys, `fresh.ts` for fresh proof, `recovery.ts` for recovery links), `routes/` (account and setup, mailbox registry, people, keys, recovery, reply and forward, the original of a message, the connection to the open app), `durableObject/` (`MailboxDO`; `live.ts` wraps its every method, so a write tells the open app; outgoing mail waits there and leaves from its one alarm: `submissions.ts` has the states, `leaving.ts` the one function that calls the send binding, `alarm.ts` the one that sets the alarm), `lib/` (pure helpers: `inbound.ts`, `filenames.ts`, `features.ts`, `list-options.ts`, `mailbox-rpc.ts`, `secrets.ts`, `models.ts` with every Workers AI model id, `ai.ts`), `agent/` (the assistant: `tools.ts`, `auto-draft.ts`, `prompt.ts`) and `mcp/server.ts` (the MCP endpoint; its tool list is `shared/mcp-tools.ts`), both optional features. +- `workers/` — the Worker: `app.ts` (entry, `fetch` and `email`), `index.ts` (API routes), `arrival.ts` (inbound mail: the original kept, then parsed and filed), `auth/` (Better Auth configuration, `authorize.ts`, the route table, the guard, the D1 index store, invitations and members, `keys.ts` for program keys, `fresh.ts` for fresh proof, `used-codes.ts` so an authenticator code is used once, `recovery.ts` for recovery links), `routes/` (account and setup, mailbox registry, people, keys, recovery, reply and forward, the original of a message, the connection to the open app), `durableObject/` (`MailboxDO`; `live.ts` wraps its every method, so a write tells the open app; outgoing mail waits there and leaves from its one alarm: `submissions.ts` has the states, `leaving.ts` the one function that calls the send binding, `alarm.ts` the one that sets the alarm), `lib/` (pure helpers: `inbound.ts`, `filenames.ts`, `features.ts`, `list-options.ts`, `mailbox-rpc.ts`, `secrets.ts`, `models.ts` with every Workers AI model id, `ai.ts`), `agent/` (the assistant: `tools.ts`, `auto-draft.ts`, `prompt.ts`) and `mcp/server.ts` (the MCP endpoint; its tool list is `shared/mcp-tools.ts`), both optional features. - `app/` — the single-page app: `router.tsx` (the route tree), `routes/`, `components/`, `queries/` (TanStack Query), `services/api.ts`, and `lib/mail-html.ts`, the only renderer of mail HTML. - `shared/` — code both sides import: `log.ts` (the only module that writes logs), `live.ts` (the one message a mailbox sends the open app: four counters, no mail), `html-text.ts` (text of an HTML fragment, no DOM), `security-headers.ts` (the response headers and the two content policies; `public/_headers` is generated from it), `mail-frame.ts` (the one inline script, with the hash the page's policy names), `attachment-risk.ts` (which attachments can do harm, and the type a file is served as), `mcp-tools.ts`, `fresh-proof.ts`, `choices.ts` (the schema of a person's choices; `choices-schema.ts` is its strict half, loaded by the Worker only), `known-addresses.ts`. No Node-only and no browser-only API. - `migrations/` — D1: `0001_auth.sql` is generated by Better Auth and never edited; `0002_index.sql` is Podbay's index (roles, mailboxes, memberships, audit); `0003` to `0006` add invitations, keys, the second step (generated, like `0001`) and recovery links; `0007` adds a person's choices. Additive only. diff --git a/docs/auth-and-access.md b/docs/auth-and-access.md index f612f63..51ff85b 100644 --- a/docs/auth-and-access.md +++ b/docs/auth-and-access.md @@ -28,7 +28,7 @@ Better Auth is used for identity only. Authorisation is Podbay's own code, in on | Topic | Design | |---|---| -| Methods | Password, passkey, or both. An authenticator app with recovery codes as the second step. A passkey satisfies the second step by itself: it is bound to the site and must verify the person. There are no trusted devices and no codes by mail or text message: a mail product cannot mail a code to the mailbox being opened | +| Methods | Password, passkey, or both. An authenticator app with recovery codes as the second step. A passkey satisfies the second step by itself: it is bound to the site and must verify the person. A code from the app works once. There are no trusted devices and no codes by mail or text message: a mail product cannot mail a code to the mailbox being opened | | New accounts | By invitation only. An administrator creates a single-use invitation link. There is no open registration, ever | | First owner | A new instance is closed. The first owner is created only by a call that carries the setup token the deployer set. The setup page never trusts the first visitor | | Sessions | Server-side sessions in D1. Cookies are host-only, `HttpOnly`, `Secure`, `SameSite=Lax`. A person sees and can end their sessions. A password change ends all of them | diff --git a/docs/status.md b/docs/status.md index f11fab8..75f4bb7 100644 --- a/docs/status.md +++ b/docs/status.md @@ -35,9 +35,10 @@ | The page loads only its own script, style, fonts and API: no host, no wildcard, no `eval`, one inline script by hash (the mail frame's sizing script). The mail frame needs nothing the page does not allow and stays narrower. Whatever the Worker answers has a policy that allows nothing and is sandboxed | S4, S11 | `test/unit/content-policy.test.ts`, `pnpm static headers` | | An attachment leaves as a download with `nosniff` and a type the sender did not choose; one that can do harm (program, script, macro document, page, shortcut, archive, deceptive name) is refused to a link and handed over only to a POST from the app's own origin that says so; a risky file is always opaque bytes; images a message embeds reach the frame as `data:` URLs, plain image kinds only | S5 | `test/workerd/attachments.test.ts`, `test/unit/attachment-risk.test.ts`, `test/unit/content-policy.test.ts` | | Invitations work once, for the invited address, until they expire or are revoked; the token is never stored; a mailbox keeps an owner | S10 | `test/workerd/people.test.ts` | -| An authenticator app stands between the password and a session once enabled; recovery codes work once; no trusted devices; no codes by mail; guesses are limited | S10 | `test/workerd/second-step.test.ts` | +| An authenticator app stands between the password and a session once enabled; recovery codes work once; no trusted devices; no codes by mail; guesses are limited; a code from the app is used once, across isolates (the one that turned the app on, one that signed in, and the same code given by two sign-ins at once each let in nobody more), answered as a wrong code and stored only as an HMAC | S10 | `test/workerd/second-step.test.ts`; `pnpm e2e`: `sign-in.spec.ts` | | A passkey is a complete sign-in, bound to this site, and must verify the person; an unknown passkey, another site's answer and a replayed answer are refused | S10 | `test/workerd/second-step.test.ts` (software authenticator in `test/helpers/authenticator.ts`) | -| Sensitive changes need a session that signed in within ten minutes, read from the database: keys, invitations, members, deleting a mailbox, forwarding, and every Better Auth endpoint that changes how a person signs in; signing in again replaces the session | S10 (step-up) | `test/workerd/second-step.test.ts`, `test/unit/fresh.test.ts` | +| Sensitive changes need a session that signed in within ten minutes, read from the database: keys, invitations, members, deleting a mailbox, forwarding, and every Better Auth endpoint that changes how a person signs in; signing in again replaces the session. Forwarding is changed on the route that saves a mailbox's settings, marked `sensitive` in the route table so that its session is read from the database too; only such a route reads the flag | S10 (step-up) | `test/workerd/second-step.test.ts`, `test/unit/fresh.test.ts` | +| The route that moves one message takes Sent as a target never, and Drafts only for a draft (a message the mailbox wrote and that never left), which is how the app undoes deleting one; mail that arrived, also old mail without an original and mail without a Message-ID, and mail that left are refused with `NOT_A_TARGET` and stay where they were | S1 | `test/workerd/move.test.ts` | | A recovery link is issued by someone else (an owner for anyone, an administrator for members, the operator with the setup token for an owner), never for oneself and never without fresh proof; it works once, for a day, stored as a digest; using it sets a new password, ends every session, removes the authenticator app and passkeys and revokes the person's keys, in one batch | S10 (recovery) | `test/workerd/recovery.test.ts`, `test/unit/recovery.test.ts` | | A mailbox owner adds people by address, changes roles and removes members; other members only see the list; a non-member is told the mailbox does not exist. Whoever manages the instance reaches the member routes and the registry without a membership and nothing else (no mail, no settings, no storage); giving themselves a membership needs fresh proof and stays on a record the mailbox's owners read, also after they remove themselves; a mailbox keeps an owner | S1, S10 | `test/workerd/members.test.ts`, `test/workerd/access.test.ts`, `test/unit/authorize.test.ts`, `test/unit/members.test.ts` | | In a real browser a hostile message runs no script, contacts no host, opens no window or dialog, cannot move or reach the app, and leaves nothing active in the frame (sixteen kinds of attack); remote images load only after the reader asks, and only over https; an embedded image needs no request; a link opens an ordinary window with no handle on the app; no page of the app breaks its own policy; the page's policy alone stops any inline script in a frame but the sizing script | S4, S11 | `pnpm e2e`: `hostile-mail.spec.ts`, `mail-frame.spec.ts`, `policy.spec.ts` | @@ -106,8 +107,7 @@ Gaps that are open on purpose until their milestone, all behind features that ar - **An owner or administrator of the instance can take any mailbox**: add themselves, even replace its owners. That is what managing memberships means; what stands against misuse is fresh proof, the audit log and the record the mailbox's owners can read. Nobody is told when it happens: an owner sees it only when they open the members page. The record is read from audit rows by the mailbox's address. - **Recovery always needs a second person or the operator.** There is no self-service reset: Podbay cannot mail a link yet, and a recovery address outside Podbay is not built. Whoever issues a link decides, outside Podbay, that the person asking is who they say. Nobody is required to have a second step yet, not even owners. - **The setup token is a standing credential once recovery exists**: whoever holds `SETUP_TOKEN` can take over an owner account through `POST /api/setup/recovery`. A deployer who does not want that removes the secret after setup and sets a new one only when an owner must be recovered; without the secret the call answers 503. Podbay's own public routes (setup, invitations, recovery) are not rate-limited; their tokens are 190 random bits or more, the setup token as strong as the deployer made it (24 characters at least). -- **A code from the authenticator app can be used again within its 30 seconds**; Better Auth does not remember used codes. Passkeys are tested with a software authenticator in the Workers runtime and with Chrome's own virtual authenticator in the browser tests, not with a physical device. -- Changing forwarding is checked for fresh proof on the session copy cached in the cookie (at most a minute old); the other sensitive routes read the database. +- **A code from the authenticator app is used once** since 2026-11-18 (issue #12): Podbay claims it before Better Auth sees it, in Better Auth's own `verification` table under a key made from the person and the code, for two minutes. A code is claimed whether it is right or wrong, so a right code refused for another reason (a locked account) waits for the next one, and a person who turned the app on a moment ago signs in with the app's next code. Better Auth itself still remembers no code: the guard is Podbay's (`workers/auth/used-codes.ts`) and must stay in front of the endpoint when Better Auth is updated. Passkeys are tested with a software authenticator in the Workers runtime and with Chrome's own virtual authenticator in the browser tests, not with a physical device. - **The assistant has not been run against a real model** since its model ids and SDK were updated: its logic is tested with a fake, never with Workers AI. In chat it can still be told by a hostile message to move mail to Trash or discard drafts; it cannot send. - Storage is still named after the mailbox address and the message id, taken from the index and never from the request; opaque storage ids come with the storage work of milestone 3. The original of a message is the one exception: its key is random and is read from its row ([ADR-0015](adr/0015-the-original-message-is-kept.md)). @@ -126,7 +126,7 @@ Gaps that are open on purpose until their milestone, all behind features that ar - **Before ADR-0007, deleting a custom folder deleted its messages for good.** The mailbox's database enforces foreign keys (tried in the Workers runtime on 2026-11-17), so `ON DELETE CASCADE` did what it says, without Trash. The route is removed and custom folders became labels; no instance in use is known to have called it. - **Languages: what is left.** The Turkish catalog (830 messages on 2026-11-18, in the two files `app/i18n/tr.ts` joins) was written with the code on 2026-11-17 and has not been read through by a second person. What the Worker says stays English: the reason a request was refused, and everything the assistant and the MCP tools answer. The built-in prompt of the assistant is English. `pnpm static messages` reads markup as text, so words handed to a toast or an error as a plain string are not caught by it; they were found once with a parser on 2026-11-17 and wired by hand. - **Two owners saving a mailbox's settings at once lose one change.** The route that saves them replaces the whole object and raises `rev` without comparing it, and the app sends its cached copy with one key changed. Found on 2026-11-17 while reading for [ADR-0012](adr/0012-a-persons-choices-and-known-addresses.md); a compare on `rev` is a change of the route's contract and is not made yet. -- **Found by reading on 2026-11-17, while four records were written, and not corrected yet.** A received message's files were written to the bucket before their rows, so a failure in between left objects no row names; that was corrected on 2026-11-17 when ADR-0015 was built: a row now comes before the object it names for an arriving message as for a draft. A send that the sending service refused after the request was answered left its message in Sent though it was not sent; that was corrected on 2026-11-18, when [ADR-0016](adr/0016-outgoing-mail-waits-before-it-leaves.md) was built: a message is in Sent when the service took it, and one it refused is in Drafts with the reason. The route that moves one message takes Sent and Drafts as a target, which the tools refuse; since ADR-0014 was built the app's Undo needs it only to put a draft back into Drafts, and closing it is a change of its own. The list of a place and the count beside it group old mail without a thread id differently. The list of a place reads every message of the mailbox for each page. Each is named in the record that would close it ([ADR-0011](adr/0011-drafts-keep-their-files.md), [ADR-0014](adr/0014-acting-on-many-conversations.md)) or is rule D2's and D13's work. +- **Found by reading on 2026-11-17, while four records were written, and not corrected yet.** A received message's files were written to the bucket before their rows, so a failure in between left objects no row names; that was corrected on 2026-11-17 when ADR-0015 was built: a row now comes before the object it names for an arriving message as for a draft. A send that the sending service refused after the request was answered left its message in Sent though it was not sent; that was corrected on 2026-11-18, when [ADR-0016](adr/0016-outgoing-mail-waits-before-it-leaves.md) was built: a message is in Sent when the service took it, and one it refused is in Drafts with the reason. The route that moves one message took Sent and Drafts as a target, which the tools refuse; that was corrected on 2026-11-18 (issue #31): Sent is never a target and Drafts takes only a draft. The list of a place and the count beside it group old mail without a thread id differently. The list of a place reads every message of the mailbox for each page. Each is named in the record that would close it ([ADR-0011](adr/0011-drafts-keep-their-files.md), [ADR-0014](adr/0014-acting-on-many-conversations.md)) or is rule D2's and D13's work. - **Found by reading on 2026-11-17 for ADR-0015 and ADR-0016.** Two were corrected on 2026-11-18, when [ADR-0016](adr/0016-outgoing-mail-waits-before-it-leaves.md) was built: the sending caps counted the messages that stood in Sent, so deleting or moving sent mail gave the allowance back, and two sends at once could both pass; they now count what left, in a record of the mailbox's own, in the one object that sends. And the send ran after the request was answered and was cut off after 30 seconds; it now runs from the mailbox object's alarm, with nobody waiting for it. **Not corrected:** the id Podbay stores for a sent message is not the `Message-ID` the recipient sees: the sending service makes its own and refuses one from the caller, so an answer to mail that started here joins its conversation by subject only, and "Show headers" on a sent message shows an id that did not travel (its date is now the time it left). The service's own id is kept since ADR-0016 (`service_id` in `submissions`) and nothing reads it yet. Three more that were found then were corrected on 2026-11-17, when [ADR-0015](adr/0015-the-original-message-is-kept.md) was built: an incoming message whose text is larger than a row, and one the parser refuses, were not stored and are now messages with their originals; nothing read what the receiving service says about SPF, DKIM and DMARC, and it is now kept (not yet shown: see the next line); and a message was deleted rows first, its objects afterwards, where it is now objects first, for one message, for an emptied place and for a whole mailbox. - **The original message ([ADR-0015](adr/0015-the-original-message-is-kept.md)): what is left.** Mail that arrived before 2026-11-17 has no original and never will: the bytes are gone. Sent mail and drafts have none either: the sending service builds what leaves. **The line about SPF, DKIM and DMARC is built and not shown.** Decision 19 asks for one message with a forged field of the platform's own identifier, sent by hand to a real domain, with what arrives recorded in the ledger; that needs a real domain and was not done. Until `runtime.email.authentication_results.forged` in the [ledger](cloudflare/ledger.json) is verified, `AUTHENTICATION_SHOWN` (`shared/original.ts`) is false, the Worker leaves `authentication` out of its answer and the app says nothing about authentication; the field is kept in `auth_results` from the first day (`test/unit/original.test.ts` holds the switch to the ledger entry). **On a development instance nothing checks authentication**: the local runtime builds the message's headers from what was posted, so an `Authentication-Results` field the sender wrote with the platform's identifier is believed and stored there. An arrival that is finished later has no such field: it went with the handler that was stopped. The cut of decision 19 takes the platform's own field to be well formed: if the platform ever wrote a quoted string or a comment that it did not close, a field of the sender's that follows could close it, and what is kept would then run into the sender's field. Podbay cannot tell that case from the value; the live check is where it would show. A left-over arrival in a mailbox that gets no more mail stays as it is until mail arrives (no timer is decided), and two messages arriving at once can both take it up, in which case it may be filed as `interrupted` though it could have been read; the message and its original are kept either way. A file whose bytes could not be written after its row stays a row that is not shown, and nothing writes it again from the original. The platform does not document what the sending server is told when the handler throws (it throws only before the original is stored). The whole file passes through the browser's memory before it is saved. The local development endpoint refuses a message its own parser refuses, so the screen for a message that could not be read is tried in the browser with a text that is too large, and the other two reasons in the Workers runtime only. Deleting a mailbox does not stop mail that is arriving in the same moment: a message whose handler was past the recipient check when the mailbox went can still write into the emptied mailbox object. - **A person's choices and known addresses ([ADR-0012](adr/0012-a-persons-choices-and-known-addresses.md)): what is left.** A recipient has no name: the sending bodies carry bare addresses, so `name` stays empty until a later decision lets them carry one (decision 16); the completion already matches a name and shows it beside the address. An open tab learns of a choice made elsewhere when it is loaded or come back to, not at once ([ADR-0013](adr/0013-the-mailbox-tells-the-open-app.md)). A member can still walk the alphabet through the completion, a few answers at a time: the route is not rate-limited, like every route but sign-in. Replying to all teaches every recipient, also one a stranger put in Cc. The mailbox learns from whatever leaves through the one function that lets mail leave (ADR-0016): when mail the Worker sends by itself is built ([ADR-0008](adr/0008-rules-for-incoming-mail.md)), it leaves through the same function with the kind `auto` and must not be learned from there. Known addresses are not in an export, mail already in Sent is not read back, and there is no switch that stops a mailbox from remembering. The order of a list travels as an eleventh choice, by decision 25 of ADR-0014; ADR-0012 names ten. No route deletes an account, so that the row of choices goes with it is proven by deleting the row of the person in the database. Nothing was tried with two real devices: the second browser of the tests is a second context of the same Chrome. diff --git a/test/e2e/sign-in.spec.ts b/test/e2e/sign-in.spec.ts index 189dd33..bfbb9a2 100644 --- a/test/e2e/sign-in.spec.ts +++ b/test/e2e/sign-in.spec.ts @@ -17,14 +17,14 @@ import { expect, test } from "./fixtures.ts"; const ADA = { email: "ada@example.com", name: "Ada", password: "a long passphrase for ada" }; const root = fileURLToPath(new URL("../..", import.meta.url)); -/** The code an authenticator app shows for this secret now (RFC 6238). */ -function totp(secret: string): string { +/** The code an authenticator app shows for this secret at a time, now by default (RFC 6238). */ +function totp(secret: string, at = Date.now()): string { const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"; let bits = ""; for (const char of secret) bits += alphabet.indexOf(char).toString(2).padStart(5, "0"); const key = Buffer.from((bits.match(/.{8}/g) ?? []).map((b) => Number.parseInt(b, 2))); const counter = Buffer.alloc(8); - counter.writeUInt32BE(Math.floor(Date.now() / 30_000), 4); + counter.writeUInt32BE(Math.floor(at / 30_000), 4); const mac = createHmac("sha1", key).update(counter).digest(); const offset = (mac[19] ?? 0) & 0x0f; return ((mac.readUInt32BE(offset) & 0x7fffffff) % 1_000_000).toString().padStart(6, "0"); @@ -50,6 +50,7 @@ test("a person is invited, adds an authenticator app and a passkey, and is asked }) => { test.setTimeout(180_000); let secret = ""; + let turnedOnWith = ""; const invitation = await test.step("the owner invites a person and gets a link to pass on", async () => { @@ -92,7 +93,8 @@ test("a person is invited, adds an authenticator app and a passkey, and is asked .locator("code") .filter({ hasText: /^[A-Z2-7]{16,}$/ }) .textContent()) ?? ""; - await ada.getByLabel("Code from the app").fill(totp(secret)); + turnedOnWith = totp(secret); + await ada.getByLabel("Code from the app").fill(turnedOnWith); await ada.getByRole("button", { name: "Turn on" }).click(); await expect(ada.getByText("Save these recovery codes")).toBeVisible(); expect(await ada.locator("code span").count()).toBeGreaterThanOrEqual(8); @@ -108,12 +110,18 @@ test("a person is invited, adds an authenticator app and a passkey, and is asked await expect(code).toBeFocused(); expect((await ada.request.get("/api/v1/me")).status()).toBe(401); - await code.fill("000000"); + // A code is used once: the one that turned the app on a moment ago signs nobody in, and is + // told as any wrong code is. One wrong try only: the sign-in library limits the requests to + // the second step in ten seconds, turning the app on counts, and a fifth is refused (429). + await code.fill(turnedOnWith); + const answered = ada.waitForResponse((res) => res.url().endsWith("/two-factor/verify-totp")); await ada.getByRole("button", { name: "Continue" }).click(); + expect((await answered).status()).toBe(401); await expect(ada.getByRole("alert")).toBeVisible(); expect((await ada.request.get("/api/v1/me")).status()).toBe(401); - await code.fill(totp(secret)); + // The app's next code is accepted, and is never the one already used. + await code.fill(totp(secret, Date.now() + 30_000)); await ada.getByRole("button", { name: "Continue" }).click(); await expect(ada.getByText(`Signed in as ${ADA.email}`)).toBeVisible(); }); diff --git a/test/unit/fresh.test.ts b/test/unit/fresh.test.ts index c54f2e8..0d9fb71 100644 --- a/test/unit/fresh.test.ts +++ b/test/unit/fresh.test.ts @@ -2,6 +2,7 @@ * Fresh proof (rule S10): when a session counts as fresh, which routes need it, and that every * Better Auth path Podbay names in its rules is a real endpoint of the installed version. */ +import { readdirSync, readFileSync } from "node:fs"; import { DatabaseSync } from "node:sqlite"; import { betterAuth } from "better-auth"; import { describe, expect, it } from "vitest"; @@ -63,6 +64,42 @@ describe("the routes that need fresh proof", () => { } }); + it("are joined by the routes that decide for some requests, each read from the database", () => { + const sensitive = ROUTE_TABLE.filter((r) => r.sensitive).map((r) => `${r.method} ${r.path}`); + expect(sensitive).toEqual(["PUT /api/v1/mailboxes/:mailboxId"]); + for (const route of ROUTE_TABLE.filter((r) => r.sensitive)) { + expect(route.fresh, route.path).toBeUndefined(); + expect(route.method, route.path).not.toBe("GET"); + } + }); + + it("are decided by the flag only in the code of a route marked sensitive", () => { + // The guard sets `fresh` for every request, from the cookie's copy of the session unless + // the route is marked. A route that reads the flag and is not marked decides on that copy. + // Every way of reading it: a property, an index, `get`, and taking it apart from `c.var`. + const read = + /\bvar\s*(?:\.\s*fresh\b|\[\s*["'`]fresh["'`]\s*\])|\bget\(\s*["'`]fresh["'`]\s*\)|\{[^}]*\bfresh\b[^}]*\}\s*=\s*\w+\.var\b/g; + const readers = readdirSync("workers", { recursive: true, encoding: "utf8" }) + .filter((name) => name.endsWith(".ts") && name !== "auth/middleware.ts") + .flatMap((name) => + [...readFileSync(`workers/${name}`, "utf8").matchAll(read)].map(() => name), + ); + // One read, in the handler of the one route marked sensitive. + expect(readers).toEqual(["routes/mailboxes.ts"]); + expect(readFileSync("workers/routes/mailboxes.ts", "utf8")).toMatch( + /mailboxes\.put\("\/api\/v1\/mailboxes\/:mailboxId"[\s\S]*?!c\.var\.fresh[\s\S]*?\n\}\);/, + ); + for (const sample of [ + "c.var.fresh", + 'c.var["fresh"]', + 'c.get("fresh")', + "const { fresh } = c.var", + "const { user, fresh: ok } = c.var", + ]) { + expect(sample.match(read), sample).not.toBeNull(); + } + }); + it("use the code Better Auth uses for its own fresh-session endpoints", () => { expect(NOT_FRESH_CODE).toBe("SESSION_NOT_FRESH"); }); diff --git a/test/workerd/helpers.ts b/test/workerd/helpers.ts index f3d8308..b2ac34a 100644 --- a/test/workerd/helpers.ts +++ b/test/workerd/helpers.ts @@ -228,15 +228,36 @@ export async function json(res: Response): Promise { } /** Enable the authenticator app for a signed-in browser. Returns what the person keeps. */ -export async function enableApp(browser: Browser): Promise<{ uri: string; codes: string[] }> { +const handedOut = new Map>(); + +/** + * A code the app would accept now that no earlier call handed out for the same secret. A code + * is used once (issue #12), and the server accepts the step before and after the present one, + * so a person has three codes at a time; a test that needs more waits for none, it fails. + */ +export async function nextCode(uri: string): Promise { + const used = handedOut.get(uri) ?? new Set(); + handedOut.set(uri, used); + for (const offset of [0, 30_000, -30_000]) { + const code = await totpCode(uri, Date.now() + offset); + if (!used.has(code)) { + used.add(code); + return code; + } + } + throw new Error("Every code the app would accept now was handed out already."); +} + +export async function enableApp( + browser: Browser, +): Promise<{ uri: string; codes: string[]; confirmedWith: string }> { const enabled = await browser.post(`${AUTH}/two-factor/enable`, { password: PASSWORD }); expect(enabled.status).toBe(200); const { totpURI, backupCodes } = await json<{ totpURI: string; backupCodes: string[] }>(enabled); - const confirmed = await browser.post(`${AUTH}/two-factor/verify-totp`, { - code: await totpCode(totpURI), - }); + const confirmedWith = await nextCode(totpURI); + const confirmed = await browser.post(`${AUTH}/two-factor/verify-totp`, { code: confirmedWith }); expect(confirmed.status).toBe(200); - return { uri: totpURI, codes: backupCodes }; + return { uri: totpURI, codes: backupCodes, confirmedWith }; } export async function registerPasskey(browser: Browser, name = "Laptop"): Promise { diff --git a/test/workerd/move.test.ts b/test/workerd/move.test.ts new file mode 100644 index 0000000..246978a --- /dev/null +++ b/test/workerd/move.test.ts @@ -0,0 +1,168 @@ +/** + * The route that moves one message (issue #31). A message is in Sent because the sending + * service took it, and in Drafts because it is a draft, so: + * + * - Sent is never a target, for mail that arrived, a draft or mail that left; + * - Drafts takes back a draft from wherever it was moved, which is how the app undoes deleting + * one, and a message taken back from Scheduled, which is a draft again; + * - Drafts never takes mail that arrived, also old mail without an original, nor mail that left. + * + * Every message here is made the way the product makes it: delivered to the `email` handler, + * written through the drafts route, or sent and let leave with a send binding of the tests. + */ +import { createExecutionContext, env, waitOnExecutionContext } from "cloudflare:test"; +import { beforeAll, describe, expect, it } from "vitest"; +import worker from "../../workers/app.ts"; +import { Browser, createMailbox, inbound, json, migrate, mime, setupOwner } from "./helpers.ts"; +import { fakeSender, HOUR, inMailbox, letLeave, placeOf, rowsOf } from "./sending-helpers.ts"; + +const owner = new Browser(); +const base = (address: string) => `/api/v1/mailboxes/${encodeURIComponent(address)}`; + +let made = 0; +async function mailbox(name: string): Promise { + made += 1; + const address = `${name}-${made}@example.com`; + expect((await createMailbox(owner.cookie, address)).status).toBe(201); + return address; +} + +const move = (address: string, id: string, folderId: string) => + owner.post(`${base(address)}/emails/${id}/move`, { folderId }); + +async function received(address: string, subject: string, withId = true): Promise { + const raw = mime({ + From: "ada@sender.test", + To: address, + Subject: subject, + ...(withId ? { "Message-ID": `<${subject.replaceAll(" ", "-")}@sender.test>` } : {}), + }); + const { message } = inbound(address, raw); + const ctx = createExecutionContext(); + await worker.email(message, env, ctx); + await waitOnExecutionContext(ctx); + const rows = await rowsOf<{ id: string }>( + address, + `SELECT id FROM emails WHERE subject = '${subject}'`, + ); + expect(rows).toHaveLength(1); + return rows[0]?.id as string; +} + +async function draft(address: string, subject: string): Promise { + const res = await owner.post(`${base(address)}/drafts`, { + to: "to@elsewhere.test", + subject, + body: "

Not yet

", + }); + expect(res.status).toBe(201); + return (await json<{ id: string }>(res)).id; +} + +const message = (address: string, more: Record = {}) => ({ + to: "to@elsewhere.test", + from: address, + subject: "Hello", + html: "

Hello

", + ...more, +}); + +async function sent(address: string): Promise { + await fakeSender(address); + const res = await owner.post(`${base(address)}/emails`, message(address)); + expect(res.status).toBe(202); + const { id } = await json<{ id: string }>(res); + await letLeave(address); + expect(await placeOf(address, id)).toBe("sent"); + return id; +} + +async function refused(address: string, id: string, folderId: string, place: string) { + const res = await move(address, id, folderId); + expect(res.status, `${place} → ${folderId}`).toBe(400); + expect((await json<{ code: string }>(res)).code).toBe("NOT_A_TARGET"); + expect(await placeOf(address, id)).toBe(place); +} + +beforeAll(async () => { + await migrate(); + expect((await setupOwner()).status).toBe(201); + expect((await owner.signIn("owner@example.com")).status).toBe(200); +}); + +describe("the route that moves one message", () => { + it("never takes Sent as a target, for mail that arrived, a draft or mail that left", async () => { + const address = await mailbox("sent"); + const arrived = await received(address, "arrived"); + const written = await draft(address, "written"); + const left = await sent(address); + + await refused(address, arrived, "sent", "inbox"); + await refused(address, written, "sent", "draft"); + // Mail that left and was deleted does not go back to Sent by a move either. + expect((await move(address, left, "trash")).status).toBe(200); + await refused(address, left, "sent", "trash"); + }); + + it("takes a deleted draft back into Drafts, which is the app's Undo", async () => { + const address = await mailbox("undo"); + const written = await draft(address, "written"); + expect((await move(address, written, "trash")).status).toBe(200); + expect(await placeOf(address, written)).toBe("trash"); + expect((await move(address, written, "draft")).status).toBe(200); + expect(await placeOf(address, written)).toBe("draft"); + // Back in Drafts it is a draft again: it is saved over and can be sent. + const saved = await owner.fetch(`${base(address)}/drafts/${written}`, { + method: "PUT", + body: JSON.stringify({ to: "to@elsewhere.test", subject: "again", body: "

Now

" }), + }); + expect(saved.status).toBe(200); + }); + + it("takes back into Drafts a message taken back from Scheduled", async () => { + const address = await mailbox("unsent"); + await fakeSender(address); + const later = { send_at: new Date(Date.now() + HOUR).toISOString() }; + const res = await owner.post(`${base(address)}/emails`, message(address, later)); + expect(res.status).toBe(202); + const { id } = await json<{ id: string }>(res); + expect((await owner.post(`${base(address)}/emails/${id}/unsend`)).status).toBe(200); + expect(await placeOf(address, id)).toBe("draft"); + expect((await move(address, id, "trash")).status).toBe(200); + expect((await move(address, id, "draft")).status).toBe(200); + expect(await placeOf(address, id)).toBe("draft"); + }); + + it("never takes mail that arrived or mail that left into Drafts", async () => { + const address = await mailbox("drafts"); + const arrived = await received(address, "arrived"); + // A sender may leave the Message-ID out: the message is still not one the mailbox wrote. + const anonymous = await received(address, "no id", false); + const old = await received(address, "old mail"); + // Mail stored before originals were kept has no original, and still its header list. + await inMailbox(address, (sql) => { + sql.exec(`UPDATE emails SET raw_key = NULL, raw_size = NULL WHERE id = ?1`, old); + }); + const left = await sent(address); + + await refused(address, arrived, "draft", "inbox"); + await refused(address, anonymous, "draft", "inbox"); + await refused(address, old, "draft", "inbox"); + await refused(address, left, "draft", "sent"); + expect((await move(address, arrived, "trash")).status).toBe(200); + await refused(address, arrived, "draft", "trash"); + }); + + it("refuses a request without a place, and still moves mail between the other places", async () => { + const address = await mailbox("plain"); + const arrived = await received(address, "arrived"); + for (const body of [{}, { folderId: 7 }, null]) { + const res = await owner.post(`${base(address)}/emails/${arrived}/move`, body); + expect(res.status).toBe(400); + } + for (const place of ["archive", "spam", "trash", "inbox"]) { + expect((await move(address, arrived, place)).status, place).toBe(200); + expect(await placeOf(address, arrived)).toBe(place); + } + }); +}); diff --git a/test/workerd/second-step.test.ts b/test/workerd/second-step.test.ts index 348ca23..85231c5 100644 --- a/test/workerd/second-step.test.ts +++ b/test/workerd/second-step.test.ts @@ -21,6 +21,7 @@ import { enableApp, json, migrate, + nextCode, ORIGIN, PASSWORD, passkeySignIn, @@ -53,10 +54,22 @@ beforeAll(async () => { const owner = await signedIn("owner@example.com"); ids.owner = (await owner.me()).id ?? ""; expect((await createMailbox(owner.cookie, MAILBOX)).status).toBe(201); - for (const who of ["app", "codes", "limited", "key", "both", "stale", "outsider"]) { + for (const who of [ + "app", + "codes", + "limited", + "key", + "both", + "stale", + "outsider", + "cached", + "replay", + "race", + ]) { ids[who] = await seedUser(`${who}@example.com`, "member"); } await seedMembership(MAILBOX, ids.stale ?? "", "owner"); + await seedMembership(MAILBOX, ids.cached ?? "", "owner"); }); describe("the authenticator app", () => { @@ -106,7 +119,7 @@ describe("the authenticator app", () => { expect((await browser.me()).status).toBe(401); const right = await browser.post(`${AUTH}/two-factor/verify-totp`, { - code: await totpCode(uri), + code: await nextCode(uri), }); expect(right.status).toBe(200); expect((await browser.me()).email).toBe("app@example.com"); @@ -144,7 +157,7 @@ describe("the authenticator app", () => { expect((await browser.me()).status).toBe(401); expect( - (await browser.post(`${AUTH}/two-factor/verify-totp`, { code: await totpCode(uri) })).status, + (await browser.post(`${AUTH}/two-factor/verify-totp`, { code: await nextCode(uri) })).status, ).toBe(200); expect([...browser.jar.keys()].filter((name) => name.includes("trust"))).toEqual([]); @@ -186,6 +199,79 @@ describe("the authenticator app", () => { }); }); +describe("an authenticator code", () => { + const verify = (browser: Browser, code: string) => + browser.post(`${AUTH}/two-factor/verify-totp`, { code }); + async function passwordStep(email: string): Promise { + const browser = new Browser(); + const first = await browser.signIn(email); + expect((await json<{ twoFactorRedirect: boolean }>(first)).twoFactorRedirect).toBe(true); + return browser; + } + let uri: string; + let turnedOn: string; + let wrong: { status: number; body: unknown }; + + beforeAll(async () => { + const browser = await signedIn("replay@example.com"); + ({ uri, confirmedWith: turnedOn } = await enableApp(browser)); + const asked = await passwordStep("replay@example.com"); + const res = await verify(asked, "000000"); + wrong = { status: res.status, body: await res.json() }; + expect(wrong.status).toBe(401); + }); + + it("that turned the app on does not sign in", async () => { + // Still a code the server would accept by its time, so only its use can refuse it. + const accepted = await Promise.all( + [-30_000, 0, 30_000].map((offset) => totpCode(uri, Date.now() + offset)), + ); + expect(accepted).toContain(turnedOn); + const browser = await passwordStep("replay@example.com"); + const res = await verify(browser, turnedOn); + expect({ status: res.status, body: await res.json() }).toEqual(wrong); + expect((await browser.me()).status).toBe(401); + }); + + it("that signed in once does not sign in again, and the next code does", async () => { + const code = await nextCode(uri); + const first = await passwordStep("replay@example.com"); + expect((await verify(first, code)).status).toBe(200); + expect((await first.me()).email).toBe("replay@example.com"); + + const second = await passwordStep("replay@example.com"); + const res = await verify(second, code); + // Answered as a wrong code is: whoever replays it learns nothing more. + expect({ status: res.status, body: await res.json() }).toEqual(wrong); + expect((await second.me()).status).toBe(401); + + expect((await verify(second, await nextCode(uri))).status).toBe(200); + expect((await second.me()).email).toBe("replay@example.com"); + }); + + it("lets in one of two sign-ins that give it at the same moment", async () => { + const browser = await signedIn("race@example.com"); + const { uri: theirs } = await enableApp(browser); + const code = await nextCode(theirs); + const before = await sessionsOf(ids.race ?? ""); + const one = await passwordStep("race@example.com"); + const other = await passwordStep("race@example.com"); + const answers = await Promise.all([verify(one, code), verify(other, code)]); + expect(answers.map((res) => res.status).sort()).toEqual([200, 401]); + expect(await sessionsOf(ids.race ?? "")).toBe(before + 1); + }); + + it("is kept used without the code itself", async () => { + const rows = await testEnv.DB.prepare( + `select "id", "identifier", "value" from "verification" where "identifier" like 'podbay-used-code-%'`, + ).all>(); + expect(rows.results.length).toBeGreaterThan(0); + const text = JSON.stringify(rows.results); + expect(text).not.toContain(turnedOn); + expect(text).not.toContain("000000"); + }); +}); + describe("a passkey", () => { let passkey: SoftwarePasskey; @@ -385,3 +471,87 @@ describe("fresh proof for sensitive changes", () => { expect((await put(M, settings("elsewhere@outside.test"))).status).toBe(200); }); }); + +describe("forwarding, which needs fresh proof only when it changes", () => { + const M = `/api/v1/mailboxes/${encodeURIComponent(MAILBOX)}`; + const settings = (forwardTo: string, signature = "Regards") => ({ + settings: { + fromName: "Team", + forwarding: { enabled: forwardTo !== "", email: forwardTo }, + signature: { enabled: true, text: signature }, + autoReply: { enabled: false, subject: "", message: "" }, + }, + }); + const put = (browser: Browser, body: unknown) => + browser.fetch(M, { method: "PUT", body: JSON.stringify(body) }); + const forwarding = async (browser: Browser) => + ( + await json<{ settings: { forwarding: { enabled: boolean; email: string } } }>( + await browser.fetch(M), + ) + ).settings.forwarding; + + it("is decided on the session in the database, not on the copy in the cookie", async () => { + const browser = await signedIn("cached@example.com"); + expect((await put(browser, settings(""))).status).toBe(200); + // The database says the session is old; the copy cached in the cookie, made at sign-in, + // still says it is new. Only the database may decide. + await ageSessions(ids.cached ?? "", 11); + const res = await put(browser, settings("elsewhere@outside.test")); + expect(res.status).toBe(403); + expect((await json<{ code: string }>(res)).code).toBe("SESSION_NOT_FRESH"); + expect(await forwarding(browser)).toEqual({ enabled: false, email: "" }); + // The other settings are still saved by an older session. + expect((await put(browser, settings("", "Kind regards"))).status).toBe(200); + }); + + it("is refused to a session ended a moment ago, whose copy is still in the cookie", async () => { + const browser = await signedIn("cached@example.com"); + await testEnv.DB.prepare(`delete from "session" where "userId" = ?1`).bind(ids.cached).run(); + // An ordinary read may still pass on the cookie's copy for up to a minute. + expect((await browser.fetch(`${M}/emails?folder=inbox`)).status).toBe(200); + expect((await put(browser, settings("elsewhere@outside.test"))).status).toBe(401); + const owner = await signedIn("cached@example.com"); + expect(await forwarding(owner)).toEqual({ enabled: false, email: "" }); + }); + + it("is stored as it was compared, whatever form it is sent in", async () => { + const browser = await signedIn("cached@example.com"); + expect((await put(browser, settings(""))).status).toBe(200); + await ageSessions(ids.cached ?? "", 11); + browser.forget("session_data"); + // Not a change by the comparison, so an older session may save it; what is kept is the + // compared value, never a form a later reader could take for "on". + const odd = settings(""); + odd.settings.forwarding = { enabled: 1, email: ["elsewhere@outside.test"] } as never; + expect((await put(browser, odd)).status).toBe(200); + const stored = await testEnv.DB.prepare( + `select "settings" from "mailboxes" where "address" = ?1`, + ) + .bind(MAILBOX) + .first<{ settings: string }>(); + expect(JSON.parse(stored?.settings ?? "{}").forwarding).toEqual({ enabled: false, email: "" }); + }); + + it("is never set by creating a mailbox", async () => { + const owner = await signedIn("owner@example.com"); + const address = "new-box@example.com"; + const made = await createMailbox(owner.cookie, address, { + settings: { forwarding: { enabled: true, email: "elsewhere@outside.test" } }, + }); + expect(made.status).toBe(201); + const read = await owner.fetch(`/api/v1/mailboxes/${encodeURIComponent(address)}`); + expect(await forwarding(owner)).toEqual({ enabled: false, email: "" }); + expect((await json<{ settings: { forwarding: unknown } }>(read)).settings.forwarding).toEqual({ + enabled: false, + email: "", + }); + }); + + it("is changed by a session that signed in a moment ago", async () => { + const browser = await signedIn("cached@example.com"); + expect((await put(browser, settings("elsewhere@outside.test"))).status).toBe(200); + expect(await forwarding(browser)).toEqual({ enabled: true, email: "elsewhere@outside.test" }); + expect((await put(browser, settings(""))).status).toBe(200); + }); +}); diff --git a/workers/auth/middleware.ts b/workers/auth/middleware.ts index 5643e23..f5cc0d7 100644 --- a/workers/auth/middleware.ts +++ b/workers/auth/middleware.ts @@ -15,6 +15,8 @@ * 6. A route marked `upgrade` opens a WebSocket (ADR-0013). Before a session is looked for, * the request must be an upgrade (426) and name the app's own origin (403); then its * session is read from the database, as for a route marked `fresh`. + * 7. A route marked `sensitive` decides for itself whether a request needs fresh proof, so its + * session is read from the database too: the flag `fresh` it is given is never the cookie's. */ import { createMiddleware } from "hono/factory"; import { errorFields, log } from "../../shared/log"; @@ -53,7 +55,8 @@ export type ApiContext = { instanceRole: InstanceRole; /** * Whether the session signed in recently enough for a sensitive change. For a route that is - * sensitive only for some requests; routes marked `fresh` in the table never run without it. + * sensitive only for some requests, marked `sensitive` in the table so that this is read from + * the database; routes marked `fresh` never run without it. */ fresh: boolean; /** @@ -190,8 +193,11 @@ export const guard = createMiddleware(async (c, next) => { headers: c.req.raw.headers, // A sensitive change is decided on the session in the database, never on the copy cached // in the cookie: a session revoked a moment ago must not pass. A connection that stays - // open is opened on the same footing. - query: { disableCookieCache: entry?.fresh === true || entry?.upgrade === true }, + // open is opened on the same footing, and so is a route that decides by `fresh` itself. + query: { + disableCookieCache: + entry?.fresh === true || entry?.upgrade === true || entry?.sensitive === true, + }, }); } catch (error) { if (error instanceof AuthNotConfigured) { diff --git a/workers/auth/options.ts b/workers/auth/options.ts index 1bfcfc9..3147654 100644 --- a/workers/auth/options.ts +++ b/workers/auth/options.ts @@ -22,6 +22,7 @@ import { REFUSED_AUTH_PATHS, SECOND_STEP_VERIFY_PATHS, } from "./fresh.ts"; +import { CODE_PATH, claimCode } from "./used-codes.ts"; export interface AuthConfig { /** A D1 database in the Worker; an in-memory SQLite database when generating the tables. */ @@ -72,6 +73,8 @@ async function beforeAuthEndpoint(ctx: HookContext): Promise { throw new APIError("FORBIDDEN", { message: NOT_FRESH.error, code: NOT_FRESH_CODE }); } } + // Last, so that a request refused above uses up no code: an authenticator code is used once. + if (ctx.path === CODE_PATH) await claimCode(ctx); } /** diff --git a/workers/auth/route-table.ts b/workers/auth/route-table.ts index bcc203a..12b8cd3 100644 --- a/workers/auth/route-table.ts +++ b/workers/auth/route-table.ts @@ -20,6 +20,11 @@ import type { Action } from "./authorize"; * the session cookie from any page of the same site, and what it opens stays open, so the * guard is stricter for it than for a read: the request must be an upgrade, it must name the * app's own origin, and its session is read from the database (workers/auth/middleware.ts). + * + * `sensitive` marks a route where only some requests are a sensitive change, so the route itself + * decides whether fresh proof is needed, by the flag the guard sets. Its session is read from the database, + * as for a route marked `fresh`: the copy cached in the cookie can be a minute old and says the + * session is as fresh as when the copy was made. */ export type RouteRight = Action | "public"; @@ -29,6 +34,7 @@ export interface RouteEntry { readonly right: RouteRight; readonly fresh?: true; readonly upgrade?: true; + readonly sensitive?: true; } const M = "/api/v1/mailboxes/:mailboxId"; @@ -73,7 +79,8 @@ export const ROUTE_TABLE: readonly RouteEntry[] = [ // One mailbox { method: "GET", path: M, right: "mailbox.read" }, - { method: "PUT", path: M, right: "mailbox.manage" }, + // Changing where the mailbox forwards its mail needs fresh proof; its other settings do not. + { method: "PUT", path: M, right: "mailbox.manage", sensitive: true }, { method: "DELETE", path: M, right: "mailbox.manage", fresh: true }, // The mailbox tells the open app that something changed (ADR-0013). Being told is a way of // reading, so whoever may read may listen; what is told is four counters and no mail. diff --git a/workers/auth/used-codes.ts b/workers/auth/used-codes.ts new file mode 100644 index 0000000..628569b --- /dev/null +++ b/workers/auth/used-codes.ts @@ -0,0 +1,106 @@ +// Copyright 2026 Cloudhal and the Podbay contributors +// Licensed under the Apache 2.0 license found in the LICENSE file. + +/** + * An authenticator code is used once (issue #12). Better Auth accepts a code for the step it + * belongs to and the steps on either side of it, about ninety seconds, and remembers nothing: + * someone who sees a code being typed could use it again in that time. + * + * Before a code reaches Better Auth it is claimed for the person it is typed for, by writing a + * row of Better Auth's own `verification` table whose primary key is made from that person and + * that code. The key is unique, so of two requests with the same code only one row is written, + * whichever isolate each runs in; the other is answered as a wrong code is, and Better Auth + * never sees it. A row is kept for longer than a code is accepted and is then replaced. + * + * A code is claimed whether it turns out right or wrong: a wrong one is no loss, and a right + * one refused for another reason (a locked account) waits for the next step. Nothing of the + * code is stored: the key is an HMAC under the instance secret. + * + * This module has no Cloudflare import (see workers/auth/options.ts). + */ +import { APIError, type createAuthMiddleware, getSessionFromCtx } from "better-auth/api"; + +type HookContext = Parameters[0]>[0]; + +/** The endpoint that takes a code from the authenticator app, to sign in or to turn it on. */ +export const CODE_PATH = "/two-factor/verify-totp"; + +/** How long a code stays used. Longer than the ~90 seconds in which Better Auth accepts it. */ +export const USED_CODE_SECONDS = 120; + +/** The prefix of the rows this module writes; nothing else in the table starts with it. */ +export const USED_CODE_PREFIX = "podbay-used-code-"; + +/** Better Auth's own name of the cookie that holds a sign-in between its two steps. */ +const SIGN_IN_COOKIE = "two_factor"; + +/** What Better Auth answers for a wrong code. A used code is answered the same way. */ +const WRONG_CODE = { message: "Invalid code", code: "INVALID_CODE" } as const; + +async function keyOf(secret: string, userId: string, code: string): Promise { + const key = await crypto.subtle.importKey( + "raw", + new TextEncoder().encode(secret), + { name: "HMAC", hash: "SHA-256" }, + false, + ["sign"], + ); + const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${userId}\n${code}`)); + const hex = [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join(""); + return `${USED_CODE_PREFIX}${hex}`; +} + +/** + * The person a code is typed for: the signed-in person while the app is turned on, or the one + * whose password step the sign-in cookie names. Null when neither is there; Better Auth then + * refuses the request by itself. + */ +async function personOf(ctx: HookContext): Promise { + const session = await getSessionFromCtx(ctx, { disableCookieCache: true }).catch(() => null); + if (session) return session.user.id; + const cookie = ctx.context.createAuthCookie(SIGN_IN_COOKIE).name; + const pending = await ctx.getSignedCookie(cookie, ctx.context.secret); + if (!pending) return null; + const row = await ctx.context.internalAdapter.findVerificationValue(pending); + return row?.value ?? null; +} + +/** + * Claims the code of this request for its person, or refuses it as a wrong code when it was + * claimed already. A request without a code, or without a person, is left to Better Auth. + */ +export async function claimCode(ctx: HookContext): Promise { + const code = (ctx.body as { code?: unknown } | undefined)?.code; + if (typeof code !== "string" || code === "") return; + const userId = await personOf(ctx); + if (userId === null) return; + + const id = await keyOf(ctx.context.secret, userId, code); + const now = new Date(); + // A claim that has run out is replaced: the same six digits come round again some day. + await ctx.context.adapter.deleteMany({ + model: "verification", + where: [ + { field: "id", value: id }, + { field: "expiresAt", operator: "lt", value: now }, + ], + }); + try { + await ctx.context.adapter.create({ + model: "verification", + data: { + id, + identifier: id, + value: userId, + expiresAt: new Date(now.getTime() + USED_CODE_SECONDS * 1000), + createdAt: now, + updatedAt: now, + }, + forceAllowId: true, + }); + } catch { + // The row is there: this code was used. Anything else that stops the write also + // refuses the code, which is the safe side. + throw new APIError("UNAUTHORIZED", WRONG_CODE); + } +} diff --git a/workers/durableObject/drafts.ts b/workers/durableObject/drafts.ts index c8fb247..cef4f2a 100644 --- a/workers/durableObject/drafts.ts +++ b/workers/durableObject/drafts.ts @@ -61,6 +61,22 @@ const isDraft = (sql: SqlStorage, id: string): boolean => [...sql.exec(`SELECT 1 FROM emails WHERE id = ?1 AND folder_id = ?2`, id, Folders.DRAFT)].length > 0; +/** + * Whether a message is a draft wherever it is now: the mailbox wrote it and it never left. A + * draft is stored without a Message-ID, a header list or an original, and keeps none of them + * until it is sent; a message that left has the first two, one that arrived has the second or + * the third, and one taken back from Scheduled is given none again. A draft in Trash is one + * that was deleted, and only such a message may go back to Drafts (issue #31). + */ +export const writtenHere = (sql: SqlStorage, id: string): boolean => + [ + ...sql.exec( + `SELECT 1 FROM emails WHERE id = ?1 AND message_id IS NULL AND raw_headers IS NULL + AND raw_key IS NULL AND unparsed IS NULL`, + id, + ), + ].length > 0; + const filesOf = (sql: SqlStorage, draftId: string): FileRow[] => [...sql.exec(`SELECT * FROM attachments WHERE email_id = ?1`, draftId)] as unknown as FileRow[]; diff --git a/workers/durableObject/index.ts b/workers/durableObject/index.ts index 4f115de..5c67a5c 100644 --- a/workers/durableObject/index.ts +++ b/workers/durableObject/index.ts @@ -30,6 +30,8 @@ import { threadOfReferences, threadOfSubject } from "./threads"; /** What a method answers for a message that waits to leave: nothing else changes it. */ const SCHEDULED = "scheduled" as const; +/** What a move answers when the place cannot take that message. */ +const NOT_A_TARGET = "not_a_target" as const; export class MailboxDO extends DurableObject { declare __DURABLE_OBJECT_BRAND: never; @@ -466,11 +468,17 @@ export class MailboxDO extends DurableObject { /** * Moves one message. Scheduled is neither a source nor a target: a message enters and - * leaves it only by being sent, taken back or let go (ADR-0016, decision 2). + * leaves it only by being sent, taken back or let go (ADR-0016, decision 2). Sent is never a + * target, since a message is there because the sending service took it, and Drafts takes + * back only a draft, which is how the app undoes deleting one (issue #31). */ async moveEmail(id: string, folderId: string) { if (folderId === Folders.SCHEDULED) return SCHEDULED; if (submissions.inScheduled(this.ctx.storage.sql, id)) return SCHEDULED; + if (folderId === Folders.SENT) return NOT_A_TARGET; + if (folderId === Folders.DRAFT && !drafts.writtenHere(this.ctx.storage.sql, id)) { + return NOT_A_TARGET; + } const folder = this.db .select({ id: schema.folders.id }) .from(schema.folders) diff --git a/workers/index.ts b/workers/index.ts index 7e3f6d0..dfea707 100644 --- a/workers/index.ts +++ b/workers/index.ts @@ -164,10 +164,16 @@ app.delete("/api/v1/mailboxes/:mailboxId/emails/:id", async (c: AppContext) => { }); app.post("/api/v1/mailboxes/:mailboxId/emails/:id/move", async (c: AppContext) => { - const { folderId } = (await c.req.json()) as { folderId: string }; + const body = (await c.req.json().catch(() => null)) as { folderId?: unknown } | null; + const folderId = body?.folderId; + if (typeof folderId !== "string") return c.json({ error: "Invalid request" }, 400); const moved = await c.var.mailboxStub.moveEmail(c.req.param("id")!, folderId); // Scheduled is neither a source nor a target: only a send fills it (ADR-0016, decision 2). if (moved === "scheduled") return c.json(WAITS, 409); + // Sent is filled by sending, and Drafts takes back only a draft (issue #31). + if (moved === "not_a_target") { + return c.json({ error: "This place cannot take that message", code: "NOT_A_TARGET" }, 400); + } return moved ? c.json({ status: "moved" }) : c.json({ error: "Folder not found" }, 400); }); diff --git a/workers/routes/mailboxes.ts b/workers/routes/mailboxes.ts index 9ae13e7..a74ebd8 100644 --- a/workers/routes/mailboxes.ts +++ b/workers/routes/mailboxes.ts @@ -80,10 +80,12 @@ mailboxes.post("/api/v1/mailboxes", async (c) => { const settings = { fromName: parsed.data.name, - forwarding: { enabled: false, email: "" }, signature: { enabled: false, text: "" }, autoReply: { enabled: false, subject: "", message: "" }, ...parsed.data.settings, + // A new mailbox never forwards. Whoever creates one may not be able to read it, and + // forwarding is changed on its own route, with fresh proof. + forwarding: { enabled: false, email: "" }, }; if (JSON.stringify(settings).length > MAX_SETTINGS_BYTES) { return c.json({ error: "Settings are too large" }, 400); @@ -123,17 +125,13 @@ mailboxes.put("/api/v1/mailboxes/:mailboxId", async (c) => { if ((before.enabled !== after.enabled || before.email !== after.email) && !c.var.fresh) { return c.json(NOT_FRESH, 403); } - await updateMailboxSettings( - c.env.DB, - mailbox.id, - parsed.data.settings, - c.var.user.id, - mailbox.address, - ); + // What is stored is what was compared: forwarding in its one shape, never the raw value. + const settings = { ...parsed.data.settings, forwarding: after }; + await updateMailboxSettings(c.env.DB, mailbox.id, settings, c.var.user.id, mailbox.address); // The settings are in the index, so the mailbox object is told that they changed: it is // the one change to a mailbox that is not made in it (ADR-0013, decision 6). await settingsSaved(c.var.mailboxStub); - return c.json(view({ ...mailbox, settings: parsed.data.settings }, mailbox.role)); + return c.json(view({ ...mailbox, settings }, mailbox.role)); }); /**