@snagset/server 0.0.1

package/dist/mail/resend.js

@@ -0,0 +1,95 @@
+/**
+ * The `http` adapter — Resend (D57).
+ *
+ * ONE of the two modules in this codebase allowed to touch a mail transport;
+ * `mail.test.ts` asserts there is no third. Everything else depends on
+ * `Mailer`.
+ *
+ * `fetch` and nothing else: Resend's API is one POST with a JSON body and a
+ * bearer token, and its own SDK is a wrapper around exactly that. A dependency
+ * whose job is to build one request object is a dependency that has to be
+ * audited, updated and shipped inside a package whose pitch is `npx snagset`.
+ * The same argument settled S3 in this repo (aws4fetch over the AWS SDK) and it
+ * settles this.
+ */
+const ENDPOINT = "https://api.resend.com/emails";
+/**
+ * How long to wait before giving up on the API.
+ *
+ * Bounded because the caller is a JOB with a budget (`runDueJobs`), and an
+ * un-timed fetch inside a budgeted tick means the budget is a suggestion. Ten
+ * seconds is far beyond Resend's normal response and far below the 20s tick
+ * budget, so a hung request loses one job's turn rather than the whole tick.
+ */
+const TIMEOUT_MS = 10_000;
+export function createResendMailer(apiKey, from) {
+    return {
+        kind: "http",
+        from,
+        async send(mail) {
+            const res = await fetch(ENDPOINT, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    from,
+                    to: [mail.to],
+                    subject: mail.subject,
+                    text: mail.text,
+                    ...(mail.html === undefined ? {} : { html: mail.html }),
+                    // Resend takes custom headers as an object on the send payload.
+                    ...(mail.headers === undefined ? {} : { headers: mail.headers }),
+                }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok)
+                throw new Error(await describe(res));
+            // Resend answers `{ id }`. A body that does not parse is not a failure to
+            // send — the mail is already accepted — so the id is dropped rather than
+            // the send being reported as failed and retried into a duplicate.
+            const id = await res
+                .json()
+                .then((b) => b.id ?? null)
+                .catch(() => null);
+            return { id };
+        },
+    };
+}
+/**
+ * Turn a Resend error into a sentence that names the fix.
+ *
+ * The same reasoning as the S3 error mapper next door: the raw body is JSON
+ * around one useful word, and the operator reading this at 9pm needs the next
+ * step rather than the status code. The three below are the ones a first
+ * configuration actually hits — an unverified sending domain in particular,
+ * which is the single most common Resend setup failure and whose message
+ * ("domain is not verified") does not say where to go.
+ */
+async function describe(res) {
+    const body = await res.text().catch(() => "");
+    const message = (() => {
+        try {
+            return JSON.parse(body).message ?? body.slice(0, 200);
+        }
+        catch {
+            return body.slice(0, 200);
+        }
+    })();
+    if (res.status === 401 || res.status === 403) {
+        return (`resend rejected the API key (${res.status}). Check the key in SNAGSET_MAIL_URL — ` +
+            `it starts "re_" and is created at resend.com/api-keys. A key with only ` +
+            `"sending access" to a different domain fails here too.`);
+    }
+    if (res.status === 422 && /domain/i.test(message)) {
+        return (`resend refused the From address "${message}". The sending DOMAIN must be ` +
+            `verified at resend.com/domains before it will accept mail from it — ` +
+            `check SNAGSET_MAIL_FROM uses a domain you have added there.`);
+    }
+    if (res.status === 429) {
+        return `resend rate-limited us (429). The outbox will retry with backoff; no mail was lost.`;
+    }
+    return `resend returned ${res.status}: ${message}`;
+}
+//# sourceMappingURL=resend.js.map

package/dist/mail/resend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend.js","sourceRoot":"","sources":["../../src/mail/resend.ts"],"names":[],"mappings":"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"}

package/dist/mail/smtp.js

@@ -0,0 +1,315 @@
+import { createConnection } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import { randomUUID } from "node:crypto";
+/**
+ * The `smtp` adapter — the second and last module allowed to touch a mail
+ * transport (LOCK L7). `mail.test.ts` asserts there is no third.
+ *
+ * ── WHY THIS IS HAND-ROLLED ──
+ *
+ * The same argument as `resend.ts` and as this repo's S3 client: the subset of
+ * ESMTP a transactional sender needs is EHLO, optional STARTTLS, optional AUTH,
+ * MAIL/RCPT/DATA, QUIT. That is a small, rigidly specified protocol. Against it
+ * sits a dependency tree that ships inside a package whose entire pitch is
+ * `npx snagset`, and which has to be audited and updated for the life of the
+ * product.
+ *
+ * The risk is real and worth naming: a hand-rolled SMTP client that gets AUTH
+ * or line endings wrong sends NOTHING, and mail is exactly where a subtle
+ * protocol bug hides. That is why `smtp.test.ts` drives this against a real TCP
+ * server speaking real SMTP rather than against a mocked socket — the bugs this
+ * class of code has are wire bugs, and a mock cannot have them.
+ *
+ * ── TWO DECISIONS THAT REMOVE WHOLE CATEGORIES OF BUG ──
+ *
+ * **Everything is base64.** Bodies are base64 with charset=utf-8 and subjects
+ * are RFC 2047 base64 encoded-words. This is not about size — base64 is 33%
+ * bigger than quoted-printable for ASCII text. It is that the base64 alphabet
+ * contains no `.` and no CR/LF, which makes DOT-STUFFING (RFC 5321 §4.5.2)
+ * and the 998-character line limit unreachable by construction. A line of a
+ * reviewer's comment that happens to begin with a full stop is a real message
+ * that a naive sender truncates, and this is the version of the fix that cannot
+ * be forgotten in one branch.
+ *
+ * **CRLF, always, everywhere.** `\n` alone is accepted by some servers and
+ * silently mangles the message on others. One constant, used everywhere.
+ */
+const CRLF = "\r\n";
+const CONNECT_TIMEOUT_MS = 10_000;
+/** Per command. A server that accepts the connection and then stops answering
+ *  is the failure mode a socket-level timeout does not catch. */
+const REPLY_TIMEOUT_MS = 15_000;
+export function createSmtpMailer(opts) {
+    const url = new URL(opts.url);
+    const implicitTls = url.protocol === "smtps:";
+    const port = url.port ? Number(url.port) : implicitTls ? 465 : 587;
+    const host = url.hostname;
+    const user = url.username ? decodeURIComponent(url.username) : null;
+    const pass = url.password ? decodeURIComponent(url.password) : null;
+    return {
+        kind: "smtp",
+        from: opts.from,
+        async send(mail) {
+            const messageId = `<${randomUUID()}@${senderDomain(opts.from)}>`;
+            const session = await open(host, port, implicitTls);
+            try {
+                await session.expect(220);
+                let caps = await ehlo(session, host);
+                if (!implicitTls && caps.has("STARTTLS")) {
+                    await session.command("STARTTLS", 220);
+                    await session.upgrade(host);
+                    // RFC 3207 §4.2: everything the server said before STARTTLS is
+                    // discarded and EHLO is re-issued. Servers routinely advertise AUTH
+                    // only after the upgrade, so skipping this makes authentication
+                    // silently unavailable on a correctly configured server.
+                    caps = await ehlo(session, host);
+                }
+                if (user && pass)
+                    await authenticate(session, caps, user, pass);
+                await session.command(`MAIL FROM:<${opts.from}>`, 250);
+                await session.command(`RCPT TO:<${mail.to}>`, 250);
+                await session.command("DATA", 354);
+                await session.raw(build(mail, opts.from, messageId) + CRLF + "." + CRLF, 250);
+                // QUIT is best-effort: the message is accepted at the 250 above, and a
+                // server that drops the connection instead of answering QUIT has still
+                // taken it. Treating that as a send failure would retry a delivered
+                // message — the one outcome the outbox exists to prevent.
+                await session.command("QUIT", 221).catch(() => { });
+                return { id: messageId };
+            }
+            finally {
+                session.close();
+            }
+        },
+    };
+}
+/** EHLO, and the capability set it returns, upper-cased for comparison. */
+async function ehlo(session, host) {
+    const reply = await session.command(`EHLO ${clientName(host)}`, 250);
+    const caps = new Set();
+    for (const line of reply.split(CRLF).slice(1)) {
+        const verb = line.slice(4).trim().toUpperCase();
+        if (verb)
+            caps.add(verb.split(" ")[0]);
+        // AUTH's mechanisms are on the same line as the verb.
+        if (verb.startsWith("AUTH "))
+            for (const m of verb.slice(5).split(/\s+/))
+                caps.add(`AUTH=${m}`);
+    }
+    return caps;
+}
+/**
+ * AUTH, preferring PLAIN.
+ *
+ * PLAIN is one round trip and LOGIN is three; both send the password base64'd,
+ * which is encoding and not encryption — so this refuses to run at all on a
+ * connection that is not TLS. An adapter that would rather authenticate in
+ * cleartext than fail is an adapter that leaks the operator's mail password to
+ * anyone on the path, once, silently, and then works fine.
+ */
+async function authenticate(session, caps, user, pass) {
+    if (!session.secure) {
+        throw new Error("refusing to send SMTP credentials over an unencrypted connection. " +
+            "The server did not offer STARTTLS — use smtps:// (implicit TLS, usually " +
+            "port 465), or a server that supports STARTTLS on 587.");
+    }
+    if (caps.has("AUTH=PLAIN") || (!caps.has("AUTH=LOGIN") && caps.has("AUTH"))) {
+        const token = Buffer.from(`\0${user}\0${pass}`, "utf8").toString("base64");
+        await session.command(`AUTH PLAIN ${token}`, 235);
+        return;
+    }
+    if (caps.has("AUTH=LOGIN")) {
+        await session.command("AUTH LOGIN", 334);
+        await session.command(Buffer.from(user, "utf8").toString("base64"), 334);
+        await session.command(Buffer.from(pass, "utf8").toString("base64"), 235);
+        return;
+    }
+    throw new Error("the SMTP server advertised no authentication mechanism this client supports " +
+        "(PLAIN or LOGIN). Credentials were supplied in SNAGSET_MAIL_URL, so it was " +
+        "expected to need them.");
+}
+/** The message itself: headers, then either one part or a multipart pair. */
+function build(mail, from, messageId) {
+    const headers = [
+        `From: ${from}`,
+        `To: ${mail.to}`,
+        `Subject: ${encodeHeader(mail.subject)}`,
+        `Message-ID: ${messageId}`,
+        `Date: ${new Date().toUTCString()}`,
+        "MIME-Version: 1.0",
+    ];
+    // Extra headers before the Content-Type block, because everything after that
+    // point describes the BODY and a header appended there would land inside the
+    // part rather than on the message. CRLF and newline are stripped from the
+    // value: a header injection here would let anything that reaches this
+    // function add arbitrary headers, and one of them is `Bcc`.
+    for (const [name, value] of Object.entries(mail.headers ?? {})) {
+        headers.push(`${name}: ${encodeHeader(String(value).replace(/[\r\n]+/g, " "))}`);
+    }
+    if (mail.html === undefined) {
+        headers.push('Content-Type: text/plain; charset="utf-8"', "Content-Transfer-Encoding: base64");
+        return headers.join(CRLF) + CRLF + CRLF + base64Lines(mail.text);
+    }
+    // The boundary is random rather than fixed: a fixed boundary that appears in
+    // a reviewer's comment ends the part early and truncates the mail. Random
+    // does not make that impossible, but 32 hex characters makes it a
+    // non-event, where a memorable constant makes it a matter of time.
+    const boundary = `=_${randomUUID().replace(/-/g, "")}`;
+    headers.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
+    // Plain part FIRST: RFC 2046 §5.1.4 orders alternatives worst-to-best, and a
+    // client shows the LAST one it understands. Reversed, every graphical client
+    // shows the plain text.
+    const parts = [
+        `--${boundary}`,
+        'Content-Type: text/plain; charset="utf-8"',
+        "Content-Transfer-Encoding: base64",
+        "",
+        base64Lines(mail.text),
+        `--${boundary}`,
+        'Content-Type: text/html; charset="utf-8"',
+        "Content-Transfer-Encoding: base64",
+        "",
+        base64Lines(mail.html),
+        `--${boundary}--`,
+    ];
+    return headers.join(CRLF) + CRLF + CRLF + parts.join(CRLF);
+}
+/** RFC 2047 encoded-word, but only when the subject needs one: an ASCII
+ *  subject stays readable in a raw message, which matters when the thing you
+ *  are debugging is why the mail did not arrive. */
+function encodeHeader(s) {
+    // eslint-disable-next-line no-control-regex
+    if (/^[\x20-\x7E]*$/.test(s))
+        return s;
+    return `=?utf-8?B?${Buffer.from(s, "utf8").toString("base64")}?=`;
+}
+/** Base64, wrapped at 76 characters per RFC 2045 §6.8. Servers are entitled to
+ *  reject longer lines and some do. */
+function base64Lines(s) {
+    const b64 = Buffer.from(s, "utf8").toString("base64");
+    const out = [];
+    for (let i = 0; i < b64.length; i += 76)
+        out.push(b64.slice(i, i + 76));
+    return out.join(CRLF);
+}
+/** The domain half of the From address, for the Message-ID. */
+function senderDomain(from) {
+    const at = from.lastIndexOf("@");
+    const domain = at === -1 ? "" : from.slice(at + 1).replace(/[>\s]/g, "");
+    return domain || "localhost";
+}
+/** What we call ourselves in EHLO. Not the server's name — ours — and a bare
+ *  hostname is what a server expects from a client without a public FQDN. */
+function clientName(host) {
+    return /^[\d.]+$/.test(host) || host.includes(":") ? "[127.0.0.1]" : "snagset";
+}
+async function open(host, port, tls) {
+    let socket = await new Promise((resolve, reject) => {
+        const s = tls
+            ? tlsConnect({ host, port, servername: host }, () => resolve(s))
+            : createConnection({ host, port }, () => resolve(s));
+        s.setTimeout(CONNECT_TIMEOUT_MS, () => {
+            s.destroy();
+            reject(new Error(`timed out connecting to ${host}:${port} after ${CONNECT_TIMEOUT_MS}ms`));
+        });
+        s.once("error", reject);
+    });
+    let secure = tls;
+    // One buffer for the whole session. SMTP replies arrive in whatever chunks
+    // the network chose, and a reply is not complete until a line matches
+    // `NNN<space>` — the continuation form is `NNN-`. Reading per-chunk instead
+    // is the classic bug: it works locally and fails against a server that
+    // sends its multi-line EHLO in two packets.
+    let buffer = "";
+    let waiter = null;
+    let closed = null;
+    const settle = () => {
+        if (!waiter)
+            return;
+        const match = /^\d{3} [^\r\n]*\r\n/m.exec(buffer);
+        if (!match)
+            return;
+        const end = buffer.indexOf(match[0]) + match[0].length;
+        const reply = buffer.slice(0, end);
+        buffer = buffer.slice(end);
+        const w = waiter;
+        waiter = null;
+        w.resolve(reply);
+    };
+    const attach = (s) => {
+        s.setEncoding("utf8");
+        s.on("data", (chunk) => {
+            buffer += chunk;
+            settle();
+        });
+        s.on("error", (e) => {
+            closed = e;
+            waiter?.reject(e);
+            waiter = null;
+        });
+        s.on("close", () => {
+            closed ??= new Error("the SMTP server closed the connection");
+            waiter?.reject(closed);
+            waiter = null;
+        });
+    };
+    attach(socket);
+    const read = () => new Promise((resolve, reject) => {
+        if (closed)
+            return reject(closed);
+        waiter = { resolve, reject };
+        settle();
+        const timer = setTimeout(() => {
+            if (waiter) {
+                waiter = null;
+                reject(new Error(`the SMTP server did not reply within ${REPLY_TIMEOUT_MS}ms`));
+            }
+        }, REPLY_TIMEOUT_MS);
+        timer.unref();
+    });
+    const check = (reply, want, sent) => {
+        const code = Number(reply.slice(0, 3));
+        if (code !== want) {
+            // The command is echoed because "550 5.7.1 rejected" without it is
+            // unattributable — the same code means a bad sender on MAIL FROM and a
+            // bad recipient on RCPT TO.
+            throw new Error(`SMTP ${sent} → ${reply.trim()}`);
+        }
+        return reply;
+    };
+    return {
+        get secure() {
+            return secure;
+        },
+        async expect(code) {
+            return check(await read(), code, "<greeting>");
+        },
+        async command(line, code) {
+            socket.write(line + CRLF);
+            // The password is never echoed into an error message.
+            const shown = /^AUTH /.test(line) ? line.split(" ").slice(0, 2).join(" ") : line;
+            return check(await read(), code, shown);
+        },
+        async raw(payload, code) {
+            socket.write(payload);
+            return check(await read(), code, "DATA");
+        },
+        async upgrade(hostname) {
+            const plain = socket;
+            plain.removeAllListeners("data");
+            plain.removeAllListeners("error");
+            plain.removeAllListeners("close");
+            socket = await new Promise((resolve, reject) => {
+                const s = tlsConnect({ socket: plain, servername: hostname }, () => resolve(s));
+                s.once("error", reject);
+            });
+            secure = true;
+            buffer = "";
+            attach(socket);
+        },
+        close() {
+            socket.destroy();
+        },
+    };
+}
+//# sourceMappingURL=smtp.js.map

package/dist/mail/smtp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp.js","sourceRoot":"","sources":["../../src/mail/smtp.ts"],"names":[],"mappings":"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"}

package/dist/mail/unsubscribe.js

@@ -0,0 +1,134 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Hono } from "hono";
+/**
+ * One-click unsubscribe — B2, and the thing that has to exist before a single
+ * notification is sent to a reviewer.
+ *
+ * ── WHY THIS IS NOT OPTIONAL ──
+ *
+ * Until now the only notification went to the project OWNER, whose address was
+ * verified at claim time. Reviewer addresses are self-declared, and a system
+ * that mails a self-declared address on a stranger's trigger with no way out
+ * is an open relay with better manners. RFC 8058 and the bulk-sender rules at
+ * Gmail and Yahoo both say the same thing in different words: carry a
+ * one-click opt-out or expect the spam folder.
+ *
+ * ── WHY IT CANNOT USE A SESSION ──
+ *
+ * The person clicking may have lost their review link, closed the tab, or
+ * never held a session at all — and none of that is a reason to keep mailing
+ * them. So the link is not authenticated by *who is asking*; it is
+ * authenticated by being unforgeable. An HMAC over the reviewer's id, under
+ * its own key purpose (08 §4.10), is exactly that, and the separate purpose is
+ * what stops an unsubscribe link from ever being accepted as a session or a
+ * share signature.
+ *
+ * ── WHY GET DOES NOT UNSUBSCRIBE ──
+ *
+ * Mail clients and security scanners fetch every link in a message. A GET that
+ * mutates would unsubscribe people who never clicked — silently, and in a way
+ * they could not detect. So GET renders a confirmation and POST performs it,
+ * which is also precisely what RFC 8058's `List-Unsubscribe-Post` specifies:
+ * the client posts `List-Unsubscribe=One-Click`, and only a POST changes
+ * anything.
+ */
+/** `<reviewerId>.<mac>` — the whole token, opaque to the reader. */
+export function unsubscribeToken(keys, reviewerId) {
+    const mac = createHmac("sha256", keys.derive("unsubscribe")).update(reviewerId).digest("base64url");
+    return `${reviewerId}.${mac}`;
+}
+/**
+ * The reviewer id this token vouches for, or null.
+ *
+ * No `kid` and therefore no rotation overlap, deliberately: an unsubscribe
+ * link lives in somebody's mailbox for years, and the failure mode of a
+ * rotated key here is "the opt-out link in a two-year-old email stops
+ * working", which is the one outcome this whole file exists to prevent. The
+ * token authorises exactly one irreversible-in-the-safe-direction act, so a
+ * long-lived signature is the right trade.
+ */
+export function readUnsubscribeToken(keys, token) {
+    const cut = token.lastIndexOf(".");
+    if (cut <= 0)
+        return null;
+    const id = token.slice(0, cut);
+    const given = Buffer.from(token.slice(cut + 1), "base64url");
+    const want = createHmac("sha256", keys.derive("unsubscribe")).update(id).digest();
+    // Length check first: timingSafeEqual THROWS on a length mismatch rather
+    // than returning false, so a short token would be a 500 instead of a 404.
+    if (given.length !== want.length || !timingSafeEqual(given, want))
+        return null;
+    return id;
+}
+/** The header pair a notification carries. RFC 8058. */
+export function unsubscribeHeaders(baseUrl, token) {
+    return {
+        "List-Unsubscribe": `<${baseUrl.replace(/\/+$/, "")}/unsubscribe?t=${encodeURIComponent(token)}>`,
+        // Without this line the URL is treated as an ordinary link and the
+        // provider renders no unsubscribe button — the header pair is the feature,
+        // not either half of it.
+        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+    };
+}
+const page = (title, body) => `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>${title}</title>` +
+    `<style>body{font:16px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif;color:#16181d;background:#f7f7f5;` +
+    `margin:0;display:grid;place-items:center;min-height:100vh;padding:24px}` +
+    `main{background:#fff;border:1px solid #e3e3df;border-radius:6px;padding:28px 32px;max-width:34rem}` +
+    `h1{font-size:20px;margin:0 0 12px}p{margin:0 0 16px;color:#5b6270}` +
+    `button{font:inherit;padding:9px 16px;border-radius:6px;border:1px solid #2b53d8;background:#2b53d8;color:#fff;cursor:pointer}` +
+    `@media(prefers-color-scheme:dark){body{background:#101216;color:#e9eaee}main{background:#171a20;border-color:#262a33}p{color:#a2a9b8}}` +
+    `</style><main>${body}</main>`;
+export function unsubscribeRoutes(deps) {
+    const app = new Hono();
+    const { sql, keys } = deps;
+    /**
+     * Look the reviewer up WITHOUT revealing whether the id exists.
+     *
+     * A valid signature already proves the id came from us, so there is nothing
+     * to enumerate — but a "no such person" page would still tell a forwarded
+     * recipient something about somebody else's account, and the useful answer
+     * in every case is the same: you will not be mailed.
+     */
+    const nameFor = async (id) => {
+        const [row] = await sql `
+      SELECT name FROM reviewers WHERE id = ${id}::uuid AND erased_at IS NULL`;
+        return row?.name ?? null;
+    };
+    app.get("/unsubscribe", async (c) => {
+        const token = c.req.query("t") ?? "";
+        const id = readUnsubscribeToken(keys, token);
+        if (!id) {
+            return c.html(page("Link not recognised", `<h1>That link is not one of ours</h1><p>It may have been altered in transit. If you are still receiving mail you did not ask for, reply to it and a person will sort it out.</p>`), 404);
+        }
+        const name = await nameFor(id).catch(() => null);
+        return c.html(page("Stop these emails?", `<h1>Stop emailing ${name ? escapeHtml(name) : "you"} about this review?</h1>` +
+            `<p>You will stop receiving notifications about comments you wrote or replied to. ` +
+            `Your comments stay exactly as they are, and you can still open your review link at any time.</p>` +
+            `<form method="post" action="/unsubscribe"><input type="hidden" name="t" value="${escapeHtml(token)}">` +
+            `<button type="submit">Stop the emails</button></form>`));
+    });
+    app.post("/unsubscribe", async (c) => {
+        // The token arrives as a form field from our own confirmation page, or as
+        // a query parameter from a provider's one-click POST, which sends
+        // `List-Unsubscribe=One-Click` as the BODY and keeps the URL intact.
+        const form = await c.req.parseBody().catch(() => ({}));
+        const token = String(form["t"] ?? c.req.query("t") ?? "");
+        const id = readUnsubscribeToken(keys, token);
+        if (!id)
+            return c.text("not found", 404);
+        // Idempotent: clicking twice, or a provider retrying, is the same outcome
+        // as clicking once. `COALESCE` keeps the FIRST opt-out time, which is the
+        // one a deliverability complaint asks about.
+        await sql `
+      UPDATE reviewers
+         SET notifications_off_at = COALESCE(notifications_off_at, now())
+       WHERE id = ${id}::uuid`;
+        return c.html(page("Unsubscribed", `<h1>Done — no more emails</h1><p>You will not be notified about this review again. Nothing else changed.</p>`));
+    });
+    return app;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (ch) => ch === "&" ? "&amp;" : ch === "<" ? "&lt;" : ch === ">" ? "&gt;" : ch === '"' ? "&quot;" : "&#39;");
+}
+//# sourceMappingURL=unsubscribe.js.map

package/dist/mail/unsubscribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.js","sourceRoot":"","sources":["../../src/mail/unsubscribe.ts"],"names":[],"mappings":"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"}

package/dist/projectCache.js

@@ -0,0 +1,50 @@
+export class ProjectUnavailable extends Error {
+    constructor(cause) {
+        super(`the project cache could not refresh: ${cause}`);
+        this.name = "ProjectUnavailable";
+    }
+}
+export function createProjectCache(sql, opts = {}) {
+    const ttl = opts.ttlMs ?? 10_000;
+    const now = opts.now ?? (() => Date.now());
+    const entries = new Map();
+    // One in-flight query per uid: a cold cache under load would otherwise send
+    // one identical query per concurrent request, which is the stampede the
+    // cache exists to prevent.
+    const inflight = new Map();
+    async function load(uid) {
+        const rows = await sql `
+      SELECT id, org_id, uid, status, write_mode, write_mode_downgrade_at, read_mode,
+             session_epoch, config_version, config_etag, key_prefix, ip_salt
+      FROM projects WHERE uid = ${uid} AND deleted_at IS NULL
+    `;
+        return rows[0] ?? null;
+    }
+    return {
+        async get(uid) {
+            const hit = entries.get(uid);
+            if (hit && now() - hit.at < ttl)
+                return hit.row;
+            let pending = inflight.get(uid);
+            if (!pending) {
+                pending = load(uid)
+                    .then((row) => {
+                    entries.set(uid, { at: now(), row });
+                    return row;
+                })
+                    .catch((e) => {
+                    // Do NOT fall back to `hit.row`. See the header.
+                    entries.delete(uid);
+                    throw new ProjectUnavailable(e instanceof Error ? e.message : String(e));
+                })
+                    .finally(() => inflight.delete(uid));
+                inflight.set(uid, pending);
+            }
+            return pending;
+        },
+        invalidate(uid) {
+            entries.delete(uid);
+        },
+    };
+}
+//# sourceMappingURL=projectCache.js.map

package/dist/projectCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectCache.js","sourceRoot":"","sources":["../src/projectCache.ts"],"names":[],"mappings":"AAyCA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,KAAa;QACvB,KAAK,CAAC,wCAAwC,KAAK,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAgBD,MAAM,UAAU,kBAAkB,CAChC,GAAiB,EACjB,OAA+C,EAAE;IAEjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACzC,4EAA4E;IAC5E,wEAAwE;IACxE,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsC,CAAC;IAE/D,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAc;;;kCAGN,GAAG;KAChC,CAAC;QACF,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACzB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,GAAG,IAAI,GAAG,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG;gBAAE,OAAO,GAAG,CAAC,GAAG,CAAC;YAEhD,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;qBAChB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;oBACZ,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;oBACrC,OAAO,GAAG,CAAC;gBACb,CAAC,CAAC;qBACD,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;oBACpB,iDAAiD;oBACjD,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACpB,MAAM,IAAI,kBAAkB,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3E,CAAC,CAAC;qBACD,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;gBACvC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,UAAU,CAAC,GAAG;YACZ,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}