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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .claude/skills/podbay-security/SKILL.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/auth-and-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
10 changes: 5 additions & 5 deletions docs/status.md

Large diffs are not rendered by default.

20 changes: 14 additions & 6 deletions test/e2e/sign-in.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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);
Expand All @@ -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();
});
Expand Down
37 changes: 37 additions & 0 deletions test/unit/fresh.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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");
});
Expand Down
31 changes: 26 additions & 5 deletions test/workerd/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -228,15 +228,36 @@ export async function json<T>(res: Response): Promise<T> {
}

/** 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<string, Set<string>>();

/**
* 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<string> {
const used = handedOut.get(uri) ?? new Set<string>();
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<SoftwarePasskey> {
Expand Down
168 changes: 168 additions & 0 deletions test/workerd/move.test.ts
Original file line number Diff line number Diff line change
@@ -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<string> {
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<string> {
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<string> {
const res = await owner.post(`${base(address)}/drafts`, {
to: "to@elsewhere.test",
subject,
body: "<p>Not yet</p>",
});
expect(res.status).toBe(201);
return (await json<{ id: string }>(res)).id;
}

const message = (address: string, more: Record<string, unknown> = {}) => ({
to: "to@elsewhere.test",
from: address,
subject: "Hello",
html: "<p>Hello</p>",
...more,
});

async function sent(address: string): Promise<string> {
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: "<p>Now</p>" }),
});
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);
}
});
});
Loading
Loading