@pithy-sh/support 0.1.2 → 0.1.3

package/dist/inbound/guard.d.ts

@@ -0,0 +1,74 @@
+import type { SupportGuardConfig } from "../config/config";
+import { 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 declare const GUARD_WINDOW_MS: number;
+/** 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 declare function checkSize(config: SupportGuardConfig, rawBytes: number): GuardVerdict;
+/**
+ * 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 declare function checkRates(db: SupportDatabase, config: SupportGuardConfig, input: GuardInput): Promise<GuardVerdict>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/inbound/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/inbound/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,gFAAgF;AAChF,eAAO,MAAM,eAAe,QAAiB,CAAC;AAE9C,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC;AAEjF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpH,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CASpF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,YAAY,CAAC,CAqCvB"}

package/dist/inbound/guard.js

@@ -0,0 +1,78 @@
+import { SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+//#region src/inbound/guard.ts
+/**
+* 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. */
+const GUARD_WINDOW_MS = 36e5;
+/**
+* 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.
+*/
+function checkSize(config, rawBytes) {
+	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.
+*/
+async function checkRates(db, config, input) {
+	const since = /* @__PURE__ */ new Date(input.now.getTime() - GUARD_WINDOW_MS);
+	const fromSender = await db.selectFrom(SUPPORT_MESSAGES_TABLE).select((eb) => eb.fn.countAll().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().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 };
+}
+//#endregion
+export { GUARD_WINDOW_MS, checkRates, checkSize };

package/dist/inbound/handler.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityEmailHandler } from "@pithy-sh/core/src/capability/capability";
+import type { SupportWiring } from "../capability";
+/**
+ * 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 declare function createSupportEmailHandler(wiring: SupportWiring): CapabilityEmailHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/inbound/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/inbound/handler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAEvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,sBAAsB,CAkEvF"}

package/dist/inbound/handler.js

@@ -0,0 +1,82 @@
+import { supportDatabase } from "../data/tables.js";
+import { makeClassifyDispatcher, resolveDb } from "../http/resolve.js";
+import { resolveSenderUserId } from "../link/sender.js";
+import { ingestInbound } from "./ingest.js";
+import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
+//#region src/inbound/handler.ts
+/**
+* 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.
+*/
+function createSupportEmailHandler(wiring) {
+	return async (message, env) => {
+		const bindings = env;
+		const log = createWorkerLogger({
+			name: "support",
+			fields: { env: typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : "unknown" }
+		});
+		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);
+			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: () => /* @__PURE__ */ 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) {
+			log.error("support inbound handling failed", { error });
+		}
+	};
+}
+//#endregion
+export { createSupportEmailHandler };

package/dist/inbound/ingest.d.ts

@@ -0,0 +1,104 @@
+import type { R2Bucket } from "@cloudflare/workers-types";
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { SupportConfig } from "../config/config";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * Ingest — everything the `email()` handler does, with every dependency injected.
+ *
+ * The handler in `handler.ts` is a thin shell that reads bindings off `env` and calls this. That
+ * split is what makes the interesting half testable: threading, idempotency, the guard's ordering,
+ * and the attachment bounds are all exercised here against a real D1 and injected fakes, with no
+ * Worker entry involved.
+ *
+ * ## The order of operations is the design
+ *
+ * Refusals are ordered by what they cost, and persistence comes before anything that can be slow or
+ * unavailable:
+ *
+ * 1. **Size**, from the declared length, before parsing.
+ * 2. **Parse**, then **is this ours** — decided on the SMTP envelope recipient, not on a header.
+ * 3. **Rate**, which needs a database read and so goes after the free checks.
+ * 4. **Idempotency**, because Email Routing can deliver twice and the second must be a no-op.
+ * 5. **Store**, which must not fail.
+ * 6. **Dispatch classification**, which is allowed to fail — a model that is slow or briefly down
+ *    must never take the persistence of the message with it, which is the whole reason
+ *    classification is a Workflow.
+ *
+ * A message that is not ours returns `{ handled: false }` and emits nothing. Every capability's
+ * handler sees every message, so mail for the bounce handler passing through here is the normal
+ * case, not an event.
+ */
+/** What ingest did. */
+export type IngestOutcome = 
+/** Not addressed to a configured inbox — another capability's mail, or nobody's. */
+{
+    handled: false;
+    reason: "not_addressed";
+}
+/** Refused by the guard before anything was written. */
+ | {
+    handled: false;
+    reason: "rejected";
+    rejection: string;
+}
+/** Already stored under this `Message-ID`. A redelivery, and a no-op. */
+ | {
+    handled: true;
+    duplicate: true;
+    threadId: string;
+    messageId: string;
+}
+/** Stored. */
+ | {
+    handled: true;
+    duplicate: false;
+    threadId: string;
+    messageId: string;
+    /** Whether the message opened a new thread rather than continuing one. */
+    newThread: boolean;
+    /** How many attachments were stored, after the config bounds were applied. */
+    attachments: number;
+    /** Whether a classification was dispatched. False for auto-submitted mail and when AI is off. */
+    classifying: boolean;
+};
+/** Everything ingest needs, all injectable. */
+export interface IngestDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** The resolved config. */
+    config: SupportConfig;
+    /** The R2 bucket raw messages and attachments are written to. Absent means neither is kept. */
+    bucket?: R2Bucket;
+    /** Whether the FTS5 index is composed. False means search runs as a `LIKE` scan and nothing is indexed. */
+    fts: boolean;
+    /**
+     * Start the classification Workflow for a stored message. Allowed to fail and allowed to decline —
+     * an unprovisioned project has no binding, and a thread that stays `uncategorized` is a legitimate
+     * state. The inbound path deliberately ignores the outcome; the reclassify route does not, because
+     * it is answering a human.
+     */
+    dispatchClassify: (messageId: string) => Promise<boolean>;
+    /** Resolve a sender address to a user id, or null. Allowed to fail; never fatal. */
+    linkSender: (address: string) => Promise<string | null>;
+    /** The audit seam. */
+    emit: AuditEmit;
+    /** The request/invocation logger. */
+    log: Logger;
+    /** Generate a row id. */
+    newId: () => string;
+    /** Now. */
+    now: () => Date;
+}
+/** The message as it arrived, plus the envelope facts only the runtime knows. */
+export interface IngestInput {
+    /** The raw MIME bytes. */
+    raw: ArrayBuffer;
+    /** The SMTP envelope recipient — `ForwardableEmailMessage.to`. The authority on which inbox this is. */
+    envelopeTo?: string;
+    /** The SMTP envelope sender, for the log only. The `From` header is what a thread keys on. */
+    envelopeFrom?: string;
+}
+/** Ingest one inbound message. */
+export declare function ingestInbound(deps: IngestDeps, input: IngestInput): Promise<IngestOutcome>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/inbound/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/inbound/ingest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAWxB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uBAAuB;AACvB,MAAM,MAAM,aAAa;AACvB,oFAAoF;AAClF;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE;AAC7C,wDAAwD;GACtD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC3D,yEAAyE;GACvE;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACzE,cAAc;GACZ;IACE,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,KAAK,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEN,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,EAAE,EAAE,eAAe,CAAC;IACpB,2BAA2B;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,2GAA2G;IAC3G,GAAG,EAAE,OAAO,CAAC;IACb;;;;;OAKG;IACH,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,oFAAoF;IACpF,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,sBAAsB;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,WAAW;IACX,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,GAAG,EAAE,WAAW,CAAC;IACjB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA0ID,kCAAkC;AAClC,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAsShG"}