@pithy-sh/support 0.1.0

package/src/http/views.ts

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SupportMessage } from "../data/message";
+import type { SupportThread } from "../data/thread";
+import type { SenderContext } from "../link/sender";
+import type { ListedThread } from "../store/threads";
+import type {
+  SenderContextView,
+  SupportAttachmentView,
+  SupportListedThreadView,
+  SupportMessageView,
+  SupportMyMessageView,
+  SupportMyThreadView,
+  SupportThreadView,
+} from "./responses";
+
+/**
+ * The projections between a support row and the wire.
+ *
+ * Every return type is `z.output` of the matching object in `responses.ts`, so what this Worker sends
+ * and what a management client validates against are one declaration. A field added to one and not
+ * the other does not compile.
+ *
+ * **These convert dates to ISO-8601 strings, and that changes nothing on the wire.** A `Date` handed
+ * to `c.json` serializes as an ISO string already — so the bytes were always this, while the type
+ * claimed a `Date` no client ever received and no schema could describe. Converting explicitly is
+ * what makes the response statable, and it is the whole reason the fields could be typed at all.
+ *
+ * **A row is never spread.** Each projection names its fields, so a column added to
+ * `pithy_support_threads` is disclosed by a decision rather than by default — which is the same rule
+ * every other capability's admin surface follows, and the one a `SELECT *` handed to `c.json` breaks
+ * silently.
+ */
+
+/** An ISO string, or null. */
+function iso(date: Date | null | undefined): string | null {
+  return date ? date.toISOString() : null;
+}
+
+/** Project one thread row. */
+export function threadView(thread: SupportThread): SupportThreadView {
+  return {
+    id: thread.id,
+    channel: thread.channel,
+    inboxAddress: thread.inboxAddress ?? null,
+    subject: thread.subject,
+    fromAddress: thread.fromAddress,
+    fromName: thread.fromName ?? null,
+    senderAuthenticated: thread.senderAuthenticated,
+    userId: thread.userId ?? null,
+    accountLinkSource: thread.accountLinkSource ?? null,
+    declaredCategory: thread.declaredCategory ?? null,
+    category: thread.category,
+    priority: thread.priority,
+    sentiment: thread.sentiment,
+    confidence: thread.confidence ?? null,
+    model: thread.model ?? null,
+    classifiedAt: iso(thread.classifiedAt),
+    archived: thread.archived,
+    archivedAt: iso(thread.archivedAt),
+    archivedBy: thread.archivedBy ?? null,
+    messageCount: thread.messageCount,
+    firstMessageAt: thread.firstMessageAt.toISOString(),
+    lastMessageAt: thread.lastMessageAt.toISOString(),
+    createdAt: thread.createdAt.toISOString(),
+    updatedAt: thread.updatedAt.toISOString(),
+  };
+}
+
+/** Project one thread for the inbox, carrying this viewer's own read and snooze state. */
+export function listedThreadView(thread: ListedThread): SupportListedThreadView {
+  return { ...threadView(thread), read: thread.read, snoozedUntil: iso(thread.snoozedUntil) };
+}
+
+/**
+ * Project one message.
+ *
+ * The threading internals — `mimeMessageId`, `mimeInReplyTo`, `mimeReferences`, `rawKey`, `rawBytes` —
+ * are dropped. They are how a reply is stitched to its parent, and an operator would never act on one.
+ * `rawKey` in particular is the R2 object holding the message exactly as it arrived, which is the one
+ * copy of this data that has had nothing done to it.
+ */
+export function messageView(message: SupportMessage): SupportMessageView {
+  return {
+    id: message.id,
+    direction: message.direction,
+    channel: message.channel,
+    context: message.context ?? null,
+    fromAddress: message.fromAddress ?? null,
+    fromName: message.fromName ?? null,
+    toAddress: message.toAddress ?? null,
+    subject: message.subject,
+    // Already sanitized at ingest. The raw original stays in R2 and is never served here.
+    htmlBody: message.htmlBody ?? null,
+    textBody: message.textBody,
+    emailJobId: message.emailJobId ?? null,
+    receivedAt: message.receivedAt.toISOString(),
+  };
+}
+
+/**
+ * Project one thread for the person who opened it.
+ *
+ * **Built from scratch rather than from {@link threadView}, and that is the security boundary.** A
+ * submitter's view derived by omitting fields from an operator's would disclose the next column
+ * somebody adds, silently, on the day they add it — the failure would be a default rather than a
+ * decision. Starting from nothing means a field reaches a customer only because somebody wrote it
+ * here.
+ *
+ * So: no classification, no priority, no sentiment, no confidence, no model, no viewer flags, no
+ * account link, no `archivedBy`, no addresses. What is left is their conversation.
+ */
+export function myThreadView(thread: SupportThread): SupportMyThreadView {
+  return {
+    id: thread.id,
+    subject: thread.subject,
+    resolved: thread.archived,
+    messageCount: thread.messageCount,
+    lastMessageAt: thread.lastMessageAt.toISOString(),
+    createdAt: thread.createdAt.toISOString(),
+  };
+}
+
+/** Project one message for the person in the conversation. Their own attachments ride along. */
+export function myMessageView(message: SupportMessage, attachments: SupportAttachmentView[]): SupportMyMessageView {
+  return {
+    id: message.id,
+    direction: message.direction,
+    // `textBody` on both sides. An answer is composed as plain text by `reply/send.ts`, and a
+    // submission was plain text when it arrived — so there is no `htmlBody` to hand back, and nothing
+    // here needs a sanitizer because nothing here is markup.
+    body: message.textBody,
+    context: message.context ?? null,
+    attachments,
+    sentAt: message.receivedAt.toISOString(),
+  };
+}
+
+/** Project the customer context beside a conversation. */
+export function senderView(sender: SenderContext): SenderContextView {
+  return {
+    authenticated: sender.authenticated,
+    userId: sender.userId,
+    // Constant, and stated on every response rather than carried on `SenderContext`: it describes what
+    // this seam can reach, not what a lookup found. `link/sender.ts` reads `user`-subject rows only.
+    billingScope: "user",
+    // Spread rather than set to null: both are absent for an unproven sender, and an explicit null
+    // would read as "we looked and there is none" rather than "we did not look".
+    ...(sender.name === undefined ? {} : { name: sender.name }),
+    ...(sender.emailVerified === undefined ? {} : { emailVerified: sender.emailVerified }),
+    purchases: sender.purchases.map((purchase) => ({
+      id: purchase.id,
+      rail: purchase.rail,
+      productId: purchase.productId,
+      status: purchase.status,
+      environment: purchase.environment,
+      purchasedAt: purchase.purchasedAt.toISOString(),
+      expiresAt: iso(purchase.expiresAt),
+      revokedAt: iso(purchase.revokedAt),
+    })),
+    entitlements: sender.entitlements.map((entitlement) => ({
+      key: entitlement.key,
+      active: entitlement.active,
+      expiresAt: iso(entitlement.expiresAt),
+      source: entitlement.source,
+    })),
+  };
+}

package/src/inbound/authenticity.ts

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+import { getDomain } from "tldts";
+
+/**
+ * Whether a message's `From:` header is something we are entitled to believe.
+ *
+ * ## Why this exists
+ *
+ * `From:` is an unauthenticated claim. Anyone can send mail saying `From: ada@example.com`, and for
+ * every domain that publishes DMARC `p=none` — which is most small domains and plenty of large ones
+ * — a receiving MTA will deliver it rather than reject it.
+ *
+ * That claim is the join key for the customer link: it resolves to a `pithy_auth_users` row and
+ * pulls that account's name, entitlements, and itemized purchase history into a support console,
+ * where a human reads it and acts. Rendering an attacker's thread decorated with a real customer's
+ * billing history is the standard opening move of support-driven account takeover, and this
+ * capability's own `account_access` and `privacy_request` categories route exactly those messages to
+ * an operator already primed to act on them.
+ *
+ * The recipient side of this package gets the equivalent question right and says so at length: the
+ * SMTP envelope is authority, headers are not. This is that same rule applied to the sender.
+ *
+ * ## What counts as authenticated
+ *
+ * DMARC is the only verdict that asserts what we actually need — that the **`From:` domain** is
+ * aligned with something that passed. `spf=pass` alone says the *envelope* sender's domain passed,
+ * which is a different domain and is exactly the gap DMARC exists to close, so it counts only when
+ * the envelope sender aligns with the header From. `dkim=pass` alone has the same alignment gap.
+ *
+ * Absence is not a pass. A message with no `Authentication-Results` at all is unauthenticated, which
+ * is the right answer for mail that reached us through something that never checked.
+ */
+
+/** What is known about a sender's claimed identity. */
+export interface SenderAuthenticity {
+  /** Whether the `From:` header may be treated as the real sender. */
+  authenticated: boolean;
+  /** How it was established, for the log and for a dashboard to explain itself. `none` when it was not. */
+  method: "dmarc" | "spf-aligned" | "none";
+}
+
+/** The domain half of an address, lowercased. */
+function domainOf(address: string | undefined): string | undefined {
+  const normalized = parseAddress(address);
+  const at = normalized?.lastIndexOf("@") ?? -1;
+  return normalized && at > 0 ? normalized.slice(at + 1) : undefined;
+}
+
+/**
+ * Whether two domains are aligned in the relaxed sense DMARC uses — the same Organizational Domain.
+ *
+ * **This is a public-suffix lookup, not label arithmetic, because RFC 7489 §3.2 defines relaxed
+ * alignment in terms of the Organizational Domain and that term is defined by the public suffix
+ * list.** An earlier version counted labels and required a shared parent of at least two, which is a
+ * decent approximation and wrong in exactly the way approximations of security boundaries are wrong:
+ * `co.uk` has two labels, so it "aligned" with `bbc.co.uk`. Implementing the actual algorithm removes
+ * the whole class rather than the instance somebody happened to notice.
+ *
+ * `allowPrivateDomains` is on. Without it `a.github.io` and `b.github.io` both reduce to `github.io`
+ * and two unrelated people's sites align with each other; the private section of the list is what
+ * knows that `github.io` is a boundary. Stricter is the right direction for a check that gates
+ * whether a stranger's mail gets decorated with a real customer's purchase history.
+ *
+ * A domain that has no Organizational Domain at all — a bare public suffix like `co.uk`, an IP
+ * literal, `localhost` — returns `null` from `getDomain` and therefore aligns with nothing, which is
+ * the correct answer rather than a special case.
+ */
+export function domainsAlign(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b) return false;
+  const organizational = getDomain(a, { allowPrivateDomains: true });
+  return organizational !== null && organizational === getDomain(b, { allowPrivateDomains: true });
+}
+
+/**
+ * Decide whether the `From:` header is believable.
+ *
+ * Takes the parsed verdicts and both addresses rather than the whole message, so the decision is a
+ * pure function of four values and is testable without a MIME fixture.
+ */
+export function senderAuthenticity(options: {
+  /** The `Authentication-Results` verdicts, keyed by method. */
+  authResults: Record<string, string>;
+  /** The address in the `From:` header, normalized. */
+  fromAddress: string;
+  /** The SMTP envelope sender — what SPF was actually evaluated against. */
+  envelopeFrom: string | undefined;
+  /**
+   * Whether the adopter has attested that the header is worth reading at all.
+   *
+   * **Default off, and this is the load-bearing gate.** Under Cloudflare Email Routing a Worker is
+   * not reliably given the MTA's own `Authentication-Results`, and a header the *sender* wrote is
+   * indistinguishable from one an MTA wrote once the MTA's copy is absent — so reading it by default
+   * would mean believing whatever the attacker typed. Everything below is a verdict about a value
+   * that only means something once somebody has said their pipeline produces it honestly.
+   */
+  trusted: boolean;
+}): SenderAuthenticity {
+  if (!options.trusted) return { authenticated: false, method: "none" };
+
+  if (options.authResults.dmarc === "pass") return { authenticated: true, method: "dmarc" };
+
+  // SPF passed, but on the envelope sender's domain. It only tells us anything about the `From:`
+  // header when the two align — which is the check DMARC would have done for us.
+  if (options.authResults.spf === "pass") {
+    const envelope = domainOf(options.envelopeFrom);
+    const header = domainOf(options.fromAddress);
+    if (domainsAlign(envelope, header)) return { authenticated: true, method: "spf-aligned" };
+  }
+
+  return { authenticated: false, method: "none" };
+}

package/src/inbound/guard.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SupportGuardConfig } from "../config/config";
+import { SUPPORT_MESSAGES_TABLE, type SupportDatabase } from "../data/tables";
+
+/**
+ * The inbound guard — the bound between "a public support address" and "a public write endpoint into
+ * the adopter's D1", which is what one is without this file.
+ *
+ * Three checks, deliberately ordered by what they cost:
+ *
+ * 1. **Size**, from the message's declared length, before a byte is parsed. Parsing is the expensive
+ *    step and the size is known first, so refusing here is the difference between a flood costing
+ *    CPU and costing nothing.
+ * 2. **Per sender**, which catches the overwhelmingly common case: one misconfigured auto-responder
+ *    in a loop with the inbox. It is not an attack and it will still fill a database.
+ * 3. **Globally**, which is the only one that helps under a distributed flood, where every
+ *    individual address stays comfortably under the per-sender bound.
+ *
+ * ## Counted from the messages table, not from a counter table
+ *
+ * A dedicated counter row would be one write per message and a second thing to reconcile — and it
+ * would be **wrong**, because a counter incremented before the insert overcounts a failed store and
+ * one incremented after undercounts a flood. The messages table already holds the exact fact, and
+ * `(from_address, received_at)` is already indexed for the sender history the dashboard shows. So
+ * the guard is a covered index scan over data that must exist anyway, and it cannot drift from what
+ * it is counting.
+ *
+ * The window is a sliding hour rather than a fixed bucket, because a fixed bucket lets twice the
+ * limit through across a boundary — which is exactly when a retry storm arrives.
+ *
+ * ## Mail only, and the in-app channel has its own bound
+ *
+ * Both counts filter on `channel = "email"`, so an in-app submission is invisible here and a piece of
+ * mail is invisible to `submission/guard.ts`. **Neither surface may starve the other.** Counting them
+ * together would mean a burst of in-app feedback during an outage locks a paying customer's email out
+ * of the inbox, and a mail flood stops the app's own users reporting the very outage that caused it —
+ * each of which is the failure arriving at the worst possible moment. They are also bounded on
+ * different keys for a real reason: a mail sender is an address anybody can write, while a submitter is
+ * an account the adopter issued and can revoke.
+ */
+
+/** One hour, in milliseconds — the window every rate bound is measured over. */
+export const GUARD_WINDOW_MS = 60 * 60 * 1000;
+
+/** Why a message was refused. The value lands in the audit event's `metadata.reason`. */
+export type SupportRejectionReason = "too_large" | "sender_rate" | "global_rate";
+
+/** The guard's answer: accept, or refuse with a reason. */
+export type GuardVerdict = { accepted: true } | { accepted: false; reason: SupportRejectionReason; detail: string };
+
+/** What the guard needs to decide. */
+export interface GuardInput {
+  /** The raw message size in bytes, as received. */
+  rawBytes: number;
+  /** The sender's normalized address. */
+  fromAddress: string;
+  /** Now. Injected so the window is testable without waiting an hour. */
+  now: Date;
+}
+
+/**
+ * Check the size bound alone — the half that needs no database and can therefore run before the
+ * message is parsed. Split out because the ordering is the point: this is the only check available
+ * while the decision is still free.
+ */
+export function checkSize(config: SupportGuardConfig, rawBytes: number): GuardVerdict {
+  if (rawBytes > config.maxRawBytes) {
+    return {
+      accepted: false,
+      reason: "too_large",
+      detail: `raw message is ${rawBytes} bytes, over the ${config.maxRawBytes} byte bound`,
+    };
+  }
+  return { accepted: true };
+}
+
+/**
+ * Check the two rate bounds against what is already stored.
+ *
+ * Both counts run against the sliding window ending now. Inbound only: a burst of *replies* is the
+ * adopter's own doing and must never lock them out of their own inbox, which is a real failure mode
+ * for a guard that counts every row in the table.
+ */
+export async function checkRates(
+  db: SupportDatabase,
+  config: SupportGuardConfig,
+  input: GuardInput,
+): Promise<GuardVerdict> {
+  const since = new Date(input.now.getTime() - GUARD_WINDOW_MS);
+
+  const fromSender = await db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select((eb) => eb.fn.countAll<number>().as("count"))
+    .where("direction", "=", "inbound")
+    .where("channel", "=", "email")
+    .where("fromAddress", "=", input.fromAddress)
+    .where("receivedAt", ">=", since.getTime())
+    .executeTakeFirst();
+
+  if ((fromSender?.count ?? 0) >= config.maxPerSenderPerHour) {
+    return {
+      accepted: false,
+      reason: "sender_rate",
+      detail: `sender has landed ${fromSender?.count} messages in the last hour, at or over the ${config.maxPerSenderPerHour} bound`,
+    };
+  }
+
+  const total = await db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select((eb) => eb.fn.countAll<number>().as("count"))
+    .where("direction", "=", "inbound")
+    .where("channel", "=", "email")
+    .where("receivedAt", ">=", since.getTime())
+    .executeTakeFirst();
+
+  if ((total?.count ?? 0) >= config.maxPerHour) {
+    return {
+      accepted: false,
+      reason: "global_rate",
+      detail: `inbox has accepted ${total?.count} messages in the last hour, at or over the ${config.maxPerHour} bound`,
+    };
+  }
+
+  return { accepted: true };
+}

package/src/inbound/handler.ts

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CapabilityEmailHandler } from "@pithy-sh/core/src/capability/capability";
+import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
+import type { SupportWiring } from "../capability";
+import { supportDatabase } from "../data/tables";
+import { makeClassifyDispatcher, resolveDb, type SupportEnv } from "../http/resolve";
+import { resolveSenderUserId } from "../link/sender";
+import { ingestInbound } from "./ingest";
+
+/**
+ * The `email()` seam — a thin shell over `ingestInbound`.
+ *
+ * Everything interesting lives in `ingest.ts`, with every dependency injected; this file exists only
+ * to read bindings off the untyped Worker env and to make the two decisions that belong at the
+ * boundary rather than inside the orchestration.
+ *
+ * ## It never throws, and that is not laziness
+ *
+ * A Worker has one `email()` entry, and `createEntrypoint` fans every message to **every**
+ * capability that declares a handler — sequentially, in registration order. An exception thrown here
+ * would propagate out of that loop and stop the handlers after it from running, so a malformed
+ * message addressed to support could take out `@pithy-sh/email`'s bounce processing, which is how
+ * suppression stops working and an adopter's sending reputation quietly degrades. One capability's
+ * bad day must not be another's.
+ *
+ * So the handler catches, logs, and returns. The message is left untouched, which the runtime treats
+ * as a drop — correct, because a message this Worker could not store is one it cannot act on either.
+ *
+ * ## There is no request logger here
+ *
+ * `c.var.log` belongs to a `fetch`. An inbound message has no request, so the handler builds its own
+ * logger from the env rather than pretending otherwise.
+ */
+export function createSupportEmailHandler(wiring: SupportWiring): CapabilityEmailHandler {
+  return async (message, env) => {
+    const bindings = env as unknown as SupportEnv;
+    const log = createWorkerLogger({
+      name: "support",
+      fields: { env: typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : "unknown" },
+    });
+
+    // A capability configured with no addresses claims nothing. Say so once, at warn, rather than
+    // parsing every message the Worker receives to reach the same conclusion silently.
+    if (wiring.config.inboundAddresses.length === 0) {
+      log.warn("support has no inboundAddresses configured — every message is ignored", {
+        action: "Set `inboundAddresses` on the support capability in pithy.config.ts.",
+      });
+      return;
+    }
+
+    try {
+      const d1 = resolveDb(env);
+
+      // Refuse on the *declared* size before buffering. `checkSize` runs again inside ingest — it is
+      // the orchestration's own contract and must hold when called directly — but by then the whole
+      // message is already in memory, which is exactly the cost the size bound exists to avoid.
+      // `rawSize` is the runtime's own count and needs no bytes read to consult.
+      const declared = message.rawSize;
+      if (typeof declared === "number" && declared > wiring.config.guard.maxRawBytes) {
+        log.warn("support inbound message refused before parsing", {
+          reason: "too_large",
+          rawSize: declared,
+          maxRawBytes: wiring.config.guard.maxRawBytes,
+        });
+        return;
+      }
+
+      const raw = await new Response(message.raw).arrayBuffer();
+
+      const outcome = await ingestInbound(
+        {
+          db: supportDatabase(d1),
+          config: wiring.config,
+          bucket: bindings.SUPPORT_BUCKET,
+          fts: wiring.config.search.fts,
+          dispatchClassify: makeClassifyDispatcher(env, log),
+          linkSender: (address) => resolveSenderUserId(d1, address),
+          emit: wiring.emit,
+          log,
+          newId: () => crypto.randomUUID(),
+          now: () => new Date(),
+        },
+        { raw, envelopeTo: message.to, envelopeFrom: message.from },
+      );
+
+      if (outcome.handled && !outcome.duplicate) {
+        log.info("support message stored", {
+          threadId: outcome.threadId,
+          messageId: outcome.messageId,
+          newThread: outcome.newThread,
+          attachments: outcome.attachments,
+        });
+      }
+    } catch (error) {
+      // Swallowed on purpose — see the note above. The failure is logged with everything an operator
+      // needs and nothing the sender wrote.
+      log.error("support inbound handling failed", { error });
+    }
+  };
+}