@pithy-sh/support 0.1.2 → 0.1.4

package/dist/store/threads.js

@@ -0,0 +1,199 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportNotFoundError } from "../error/errors.js";
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread } from "../data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { isSearchable, searchPredicate } from "./search.js";
+import "./paging.js";
+import { sql } from "kysely";
+//#region src/store/threads.ts
+/**
+* Encode a cursor for the wire.
+*
+* Base64url over JSON, and **opaque by intent rather than by obscurity**: the point is that a client
+* cannot construct one by hand and therefore cannot come to depend on its shape, so the ordering can
+* change later without breaking every caller. It is not a secret — it holds a timestamp and an id
+* the caller was just given.
+*/
+function encodeCursor(cursor) {
+	return btoa(JSON.stringify(cursor)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decode a cursor. Returns undefined for anything malformed — a bad cursor is a first page, not a 500. */
+function decodeCursor(value) {
+	if (!value) return void 0;
+	try {
+		const json = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+		const parsed = JSON.parse(json);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const { lastMessageAt, id } = parsed;
+		if (typeof lastMessageAt !== "number" || typeof id !== "string") return void 0;
+		return {
+			lastMessageAt,
+			id
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* List threads, as one viewer sees them.
+*
+* The viewer is a parameter rather than an afterthought because the per-viewer flags are **read
+* here**: a snooze that was stored and never consulted is a button that does nothing, and `read` that
+* is never projected is a column a dashboard cannot render. Both are left-joined, so a thread with no
+* flag row for this viewer — the overwhelming majority — still appears, unread and unsnoozed.
+*/
+async function listThreads(db, query, options) {
+	try {
+		return await runListThreads(db, query, options);
+	} catch (error) {
+		if (options.fts && isMissingSearchTable(error)) {
+			options.log?.warn("support FTS index is configured but absent — falling back to a LIKE scan", { action: "Run `pithy support provision` to create and backfill it, or set `search.fts: false`." });
+			return runListThreads(db, query, {
+				...options,
+				fts: false
+			});
+		}
+		throw error;
+	}
+}
+/** Whether an error is SQLite saying the full-text index does not exist. */
+function isMissingSearchTable(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("no such table") && message.includes("pithy_support_search");
+}
+/** The listing itself, for one chosen search backend. */
+async function runListThreads(db, query, options) {
+	const limit = Math.min(Math.max(query.limit ?? 25, 1), 100);
+	const cursor = decodeCursor(query.cursor);
+	let builder = db.selectFrom(SUPPORT_THREADS_TABLE).leftJoin(SUPPORT_FLAGS_TABLE, (join) => join.onRef(`${SUPPORT_FLAGS_TABLE}.threadId`, "=", `${SUPPORT_THREADS_TABLE}.id`).on(`${SUPPORT_FLAGS_TABLE}.viewer`, "=", options.viewer)).selectAll(SUPPORT_THREADS_TABLE).select([`${SUPPORT_FLAGS_TABLE}.read as viewerRead`, `${SUPPORT_FLAGS_TABLE}.snoozedUntil as viewerSnoozedUntil`]).where((eb) => eb.or([eb(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`, "is", null), eb(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`, "<=", options.now.getTime())])).where(`${SUPPORT_THREADS_TABLE}.archived`, "=", query.archived === true ? 1 : 0);
+	if (query.category !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.category`, "=", query.category);
+	if (query.declaredCategory !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.declaredCategory`, "=", query.declaredCategory);
+	if (query.priority !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.priority`, "=", query.priority);
+	if (query.sentiment !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.sentiment`, "=", query.sentiment);
+	if (query.channel !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.channel`, "=", query.channel);
+	if (query.inbox !== void 0) builder = builder.where(`${SUPPORT_THREADS_TABLE}.inboxAddress`, "=", query.inbox);
+	if (query.q !== void 0) {
+		if (isSearchable(query.q, options.fts)) builder = builder.where(searchPredicate(query.q, options));
+		else builder = builder.where(sql`1 = 0`);
+	}
+	if (cursor) builder = builder.where((eb) => eb.or([eb(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "<", cursor.lastMessageAt), eb.and([eb(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "=", cursor.lastMessageAt), eb(`${SUPPORT_THREADS_TABLE}.id`, "<", cursor.id)])]));
+	const rows = await builder.orderBy(`${SUPPORT_THREADS_TABLE}.lastMessageAt`, "desc").orderBy(`${SUPPORT_THREADS_TABLE}.id`, "desc").limit(limit + 1).execute();
+	const page = rows.slice(0, limit).map((row) => ({
+		...SupportThread.parse(row),
+		read: row.viewerRead === 1,
+		snoozedUntil: row.viewerSnoozedUntil == null ? null : new Date(Number(row.viewerSnoozedUntil))
+	}));
+	const last = page[page.length - 1];
+	return {
+		threads: page,
+		nextCursor: rows.length > limit && last ? encodeCursor({
+			lastMessageAt: last.lastMessageAt.getTime(),
+			id: last.id
+		}) : null
+	};
+}
+/** Read one thread in full. Throws `support/not_found` when it does not exist. */
+async function readThread(db, threadId) {
+	const row = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).executeTakeFirst();
+	if (!row) throw new SupportNotFoundError({ detail: `no support thread ${threadId}` });
+	const [messages, attachments] = await Promise.all([db.selectFrom(SUPPORT_MESSAGES_TABLE).selectAll().where("threadId", "=", threadId).orderBy("receivedAt", "asc").orderBy("id", "asc").execute(), db.selectFrom(SUPPORT_ATTACHMENTS_TABLE).selectAll().where("threadId", "=", threadId).execute()]);
+	return {
+		thread: SupportThread.parse(row),
+		messages: messages.map((message) => SupportMessage.parse(message)),
+		attachments: attachments.map((attachment) => SupportAttachment.parse(attachment))
+	};
+}
+/**
+* List one account's own in-app conversations.
+*
+* **Two conditions on the `where`, and the second is not redundant.** `userId` alone would also return
+* every *email* thread this capability linked to the account — and that link was matched against an
+* address in a header nobody proved, so it names an account the sender merely claimed to be. Serving
+* those to whoever currently holds the address would turn the mail path's known weakness into a read
+* primitive, which is precisely the trade this channel exists to avoid making.
+*
+* Archived threads are included, unlike the operator inbox. An inbox hides done threads because it is a
+* work queue; a person looking at their own requests is looking for the one that was answered.
+*/
+async function listOwnThreads(db, userId, query) {
+	const limit = Math.min(Math.max(query.limit ?? 25, 1), 100);
+	const cursor = decodeCursor(query.cursor);
+	let builder = db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("userId", "=", userId).where("channel", "=", "app");
+	if (cursor) builder = builder.where((eb) => eb.or([eb("lastMessageAt", "<", cursor.lastMessageAt), eb.and([eb("lastMessageAt", "=", cursor.lastMessageAt), eb("id", "<", cursor.id)])]));
+	const rows = await builder.orderBy("lastMessageAt", "desc").orderBy("id", "desc").limit(limit + 1).execute();
+	const page = rows.slice(0, limit).map((row) => SupportThread.parse(row));
+	const last = page[page.length - 1];
+	return {
+		threads: page,
+		nextCursor: rows.length > limit && last ? encodeCursor({
+			lastMessageAt: last.lastMessageAt.getTime(),
+			id: last.id
+		}) : null
+	};
+}
+/**
+* Read one of an account's own in-app conversations.
+*
+* **A 404 for somebody else's thread, never a 403.** The two are the same answer on purpose: a 403
+* confirms the id names a real conversation, and on an inbox of other people's correspondence that
+* confirmation is itself the disclosure. The scoping is in the `where`, not in a check after the read,
+* so there is no version of this that fetches the row first and forgets to compare.
+*/
+async function readOwnThread(db, threadId, userId) {
+	const row = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).where("userId", "=", userId).where("channel", "=", "app").executeTakeFirst();
+	if (!row) throw new SupportNotFoundError({ detail: `no app thread ${threadId} owned by ${userId}` });
+	const [messages, attachments] = await Promise.all([db.selectFrom(SUPPORT_MESSAGES_TABLE).selectAll().where("threadId", "=", threadId).orderBy("receivedAt", "asc").orderBy("id", "asc").execute(), db.selectFrom(SUPPORT_ATTACHMENTS_TABLE).selectAll().where("threadId", "=", threadId).execute()]);
+	return {
+		thread: SupportThread.parse(row),
+		messages: messages.map((message) => SupportMessage.parse(message)),
+		attachments: attachments.map((attachment) => SupportAttachment.parse(attachment))
+	};
+}
+/**
+* Mark a thread done, or reopen it.
+*
+* The one shared piece of state in the model, and the write is unconditional rather than a
+* compare-and-set: archiving something already archived is not a conflict, it is the same outcome,
+* and a support console that threw on a double-click would be worse than one that did nothing.
+*/
+async function setArchived(db, threadId, archived, viewer, now) {
+	const existing = await db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where("id", "=", threadId).executeTakeFirst();
+	if (!existing) throw new SupportNotFoundError({ detail: `no support thread ${threadId}` });
+	await db.updateTable(SUPPORT_THREADS_TABLE).set({
+		archived: archived ? 1 : 0,
+		archivedAt: archived ? now.getTime() : null,
+		archivedBy: archived ? viewer : null,
+		updatedAt: now.getTime()
+	}).where("id", "=", threadId).execute();
+	return SupportThread.parse({
+		...existing,
+		archived: archived ? 1 : 0,
+		archivedAt: archived ? now.getTime() : null,
+		archivedBy: archived ? viewer : null,
+		updatedAt: now.getTime()
+	});
+}
+/** Set one viewer's private flags on a thread. Upserts on `(threadId, viewer)`. */
+async function setFlags(db, options) {
+	if (!await db.selectFrom("pithySupportThreads").select(["id"]).where("id", "=", options.threadId).executeTakeFirst()) throw new SupportNotFoundError({ detail: `no support thread ${options.threadId}` });
+	const read = options.read === void 0 ? void 0 : options.read ? 1 : 0;
+	const snoozed = options.snoozedUntil === void 0 ? void 0 : options.snoozedUntil?.getTime() ?? null;
+	await db.insertInto(SUPPORT_FLAGS_TABLE).values({
+		id: options.newId(),
+		threadId: options.threadId,
+		viewer: options.viewer,
+		read: read ?? 0,
+		snoozedUntil: snoozed ?? null,
+		createdAt: options.now.getTime(),
+		updatedAt: options.now.getTime()
+	}).onConflict((oc) => oc.columns(["threadId", "viewer"]).doUpdateSet((eb) => ({
+		read: read === void 0 ? eb.ref(`${SUPPORT_FLAGS_TABLE}.read`) : read,
+		snoozedUntil: snoozed === void 0 ? eb.ref(`${SUPPORT_FLAGS_TABLE}.snoozedUntil`) : snoozed,
+		updatedAt: options.now.getTime()
+	}))).execute();
+}
+//#endregion
+export { decodeCursor, encodeCursor, listOwnThreads, listThreads, readOwnThread, readThread, setArchived, setFlags };

package/dist/submission/encoding.d.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The largest base64 string worth decoding, derived from a decoded-byte bound.
+ *
+ * Checked **before** decoding, not after. `atob` materializes the whole result, so a client that sends
+ * fifty megabytes of base64 has already been allocated fifty megabytes of Worker memory by the time a
+ * post-hoc size check could refuse it — and the request that does that is the one an attacker sends.
+ * A little slack for padding and any whitespace a client's encoder inserted.
+ */
+export declare function maxEncodedLength(maxBytes: number): number;
+/**
+ * Decode one base64 attachment payload.
+ *
+ * Accepts the URL-safe alphabet too: a client that reached for `base64url` because its platform's
+ * default encoder produces it has not made a mistake worth a 400, and the two differ by two
+ * characters. Anything that is not base64 at all is a `validation/invalid_input`, which is what the
+ * route's own validator would have raised had the string been checkable there.
+ */
+export declare function decodeBase64(value: string, options: {
+    maxBytes: number;
+}): Uint8Array;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/submission/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/submission/encoding.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA2BrF"}

package/dist/submission/encoding.js

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/submission/encoding.ts
+/**
+* Turning a base64 attachment back into bytes.
+*
+* Base64 rather than `multipart/form-data` for the submission route, and the reason is the contract
+* rather than the encoding: every other route in this capability declares what it accepts as a Zod
+* object over JSON, validated on the route line, and a multipart body is the one shape that cannot be.
+* The cost is a third more bytes on the wire, which is why `attachments.maxBytes` is documented as a
+* bound on the **decoded** size — the number that reaches R2 and the adopter's bill.
+*/
+/** How much larger a base64 string is than the bytes it encodes: four characters per three bytes. */
+const BASE64_EXPANSION = 4 / 3;
+/**
+* The largest base64 string worth decoding, derived from a decoded-byte bound.
+*
+* Checked **before** decoding, not after. `atob` materializes the whole result, so a client that sends
+* fifty megabytes of base64 has already been allocated fifty megabytes of Worker memory by the time a
+* post-hoc size check could refuse it — and the request that does that is the one an attacker sends.
+* A little slack for padding and any whitespace a client's encoder inserted.
+*/
+function maxEncodedLength(maxBytes) {
+	return Math.ceil(maxBytes * BASE64_EXPANSION) + 4;
+}
+/**
+* Decode one base64 attachment payload.
+*
+* Accepts the URL-safe alphabet too: a client that reached for `base64url` because its platform's
+* default encoder produces it has not made a mistake worth a 400, and the two differ by two
+* characters. Anything that is not base64 at all is a `validation/invalid_input`, which is what the
+* route's own validator would have raised had the string been checkable there.
+*/
+function decodeBase64(value, options) {
+	if (value.length > maxEncodedLength(options.maxBytes)) throw new ValidationError({
+		message: "That attachment is too large.",
+		action: `Attach a file under ${options.maxBytes} bytes.`,
+		detail: `encoded attachment is ${value.length} characters, over the ${maxEncodedLength(options.maxBytes)} the ${options.maxBytes} byte bound allows`
+	});
+	const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+	let binary;
+	try {
+		binary = atob(normalized);
+	} catch (cause) {
+		throw new ValidationError({
+			message: "That attachment could not be read.",
+			action: "Send the file's bytes as a base64 string.",
+			detail: "attachment payload is not valid base64"
+		}, { cause });
+	}
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+//#endregion
+export { decodeBase64, maxEncodedLength };

package/dist/submission/guard.d.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { SupportSubmissionConfig } from "../config/config";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * The in-app submission guard — the bound between "a signed-in user may write in" and "one account is
+ * the whole inbox".
+ *
+ * ## Why this is not the mail guard with a different column
+ *
+ * `inbound/guard.ts` exists because a public address is a public write endpoint reachable by anybody
+ * with an SMTP client, and its bounds are the shape of that problem: a size cap before parsing, a
+ * per-address rate for the broken auto-responder, a global rate for the distributed flood where no
+ * single address stands out.
+ *
+ * None of that describes this surface. **A submission is attributable and revocable**: it carries an
+ * account the adopter issued, so the flood the mail guard's global bound exists for cannot happen
+ * anonymously here — an attacker needs an account per bucket of ten, and every one of them is a row an
+ * adopter can disable. What remains is one real failure, and it is the one this file bounds: a single
+ * account, hostile or looping, filling the inbox.
+ *
+ * So there is one check rather than three, and it counts on the **account** rather than the address.
+ * Not the same thing: an address is a claim in a header and an account is an identity a session
+ * proved, which is the whole distinction this channel exists to exploit.
+ *
+ * ## Counted from the messages table, and only against its own channel
+ *
+ * The same reasoning `inbound/guard.ts` states — the rows already exist, a counter row would be a
+ * second write that overcounts a failed store and undercounts a flood — over the same sliding hour,
+ * and over an index (`submitted_by_user_id`, `received_at`) that the migration creates for this.
+ *
+ * **`channel = "app"` is on the count deliberately.** Neither surface may starve the other: a customer
+ * who emailed twenty times about a billing dispute must still be able to file a bug from inside the
+ * app, and somebody filing bug reports must never consume the mail inbox's capacity. Sharing one
+ * counter would couple two threat models that have nothing in common.
+ */
+/** Why a submission was refused. The value lands in the audit event's `metadata.reason`. */
+export type SupportSubmissionRejectionReason = "account_rate" | "attachment_too_large" | "attachment_type";
+/** The guard's answer: accept, or refuse with a reason. */
+export type SubmissionVerdict = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: SupportSubmissionRejectionReason;
+    detail: string;
+};
+/**
+ * Check how much this account has already filed inside the window.
+ *
+ * `>=` rather than `>`, matching the mail guard: the bound is how many an account *may land*, so the
+ * request that would be the eleventh is refused when ten are already stored.
+ */
+export declare function checkAccountRate(db: SupportDatabase, config: SupportSubmissionConfig, input: {
+    userId: string;
+    now: Date;
+}): Promise<SubmissionVerdict>;
+/**
+ * Check one attachment against the declared bounds.
+ *
+ * Size is measured on the **decoded** bytes, which is the number that matters and not the one the
+ * request carried: a base64 payload is a third larger than what lands in R2, and bounding the encoded
+ * form would silently make the effective limit whatever `maxBytes * 0.75` happens to be.
+ *
+ * The type check is an **allowlist**, so a type nobody thought about is refused rather than accepted —
+ * the opposite default from the mail path, where refusing an unexpected type would lose a customer's
+ * bug report. It bounds what lands in the adopter's bucket; it is not what stops a stored-XSS, which
+ * is `putAttachment` writing every object as `application/octet-stream` whatever was declared.
+ */
+export declare function checkAttachment(config: SupportSubmissionConfig, input: {
+    contentType: string;
+    bytes: number;
+}): SubmissionVerdict;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/submission/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4FAA4F;AAC5F,MAAM,MAAM,gCAAgC,GAAG,cAAc,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AAE3G,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gCAAgC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAyB5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5C,iBAAiB,CAmBnB"}

package/dist/submission/guard.js

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+import { GUARD_WINDOW_MS } from "../inbound/guard.js";
+//#region src/submission/guard.ts
+/**
+* Check how much this account has already filed inside the window.
+*
+* `>=` rather than `>`, matching the mail guard: the bound is how many an account *may land*, so the
+* request that would be the eleventh is refused when ten are already stored.
+*/
+async function checkAccountRate(db, config, input) {
+	const since = new Date(input.now.getTime() - GUARD_WINDOW_MS);
+	const filed = await db.selectFrom(SUPPORT_MESSAGES_TABLE).select((eb) => eb.fn.countAll().as("count")).where("channel", "=", "app").where("direction", "=", "inbound").where("submittedByUserId", "=", input.userId).where("receivedAt", ">=", since.getTime()).executeTakeFirst();
+	if ((filed?.count ?? 0) >= config.maxPerAccountPerHour) return {
+		accepted: false,
+		reason: "account_rate",
+		detail: `account ${input.userId} has filed ${filed?.count} submissions in the last hour, at or over the ${config.maxPerAccountPerHour} bound`
+	};
+	return { accepted: true };
+}
+/**
+* Check one attachment against the declared bounds.
+*
+* Size is measured on the **decoded** bytes, which is the number that matters and not the one the
+* request carried: a base64 payload is a third larger than what lands in R2, and bounding the encoded
+* form would silently make the effective limit whatever `maxBytes * 0.75` happens to be.
+*
+* The type check is an **allowlist**, so a type nobody thought about is refused rather than accepted —
+* the opposite default from the mail path, where refusing an unexpected type would lose a customer's
+* bug report. It bounds what lands in the adopter's bucket; it is not what stops a stored-XSS, which
+* is `putAttachment` writing every object as `application/octet-stream` whatever was declared.
+*/
+function checkAttachment(config, input) {
+	if (input.bytes > config.attachments.maxBytes) return {
+		accepted: false,
+		reason: "attachment_too_large",
+		detail: `attachment is ${input.bytes} decoded bytes, over the ${config.attachments.maxBytes} byte bound`
+	};
+	if (!config.attachments.allowedContentTypes.includes(input.contentType)) return {
+		accepted: false,
+		reason: "attachment_type",
+		detail: `attachment declares ${input.contentType}, which is not in the configured allowlist`
+	};
+	return { accepted: true };
+}
+//#endregion
+export { checkAccountRate, checkAttachment };

package/dist/submission/submit.d.ts

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+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 SupportCategories } from "../data/categories";
+import { type SupportSubmissionContext } from "../data/message";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * The in-app submission path — a signed-in user opening a support thread from inside the app, without
+ * leaving it for their mail client.
+ *
+ * This is `inbound/ingest.ts` for the other channel, and it is deliberately the *same* destination:
+ * one threads table, one messages table, one classifier, one taxonomy, one console. A second package
+ * would have been a second inbox and a support person with two of them, neither holding the whole
+ * conversation — and the reply to an in-app report goes out by email regardless, because that is where
+ * the person will read it.
+ *
+ * ## What this path does not have to do
+ *
+ * `inbound/authenticity.ts` is two hundred lines earning the right to say a thread belongs to a
+ * customer, because a `From:` header is an unauthenticated claim and decorating a spoofed thread with a
+ * real customer's billing history is the opening move of support-driven account takeover.
+ *
+ * **There is no `From:` here to spoof.** `requireAuth()` proved the session before the handler ran, so
+ * the account arrives already established — and the thread records that with `accountLinkSource:
+ * "session"`, so a console can tell a link that *is* the identity from one that was matched against a
+ * header. Nothing in the submitted payload names an account, and nothing here reads one from it.
+ *
+ * ## The order of operations
+ *
+ * The mail path's rule, applied to a different shape: **refuse on the cheapest true reason first.**
+ * The two shape bounds a client controls the cost of — how many files, and how large each encoded one
+ * is — are applied at the transport boundary in `http/handlers.ts` *before* anything is decoded,
+ * because `atob` materializes its whole result and a size check after it has already been handed the
+ * allocation it meant to refuse. What is left arrives here as bytes:
+ *
+ * 0. **The declared category**, which needs no I/O at all — it is a comparison against a taxonomy this
+ *    process already holds, so it is genuinely the cheapest true reason there is.
+ * 1. **The account**, because everything else depends on the address a reply will come back to, and a
+ *    report nobody can answer is not worth storing.
+ * 2. **The rate bound**, before anything is written.
+ * 3. **The attachments**, every one checked before one is written, so a refusal never leaves half a
+ *    submission's files in the bucket.
+ * 4. **Store**, which must not fail.
+ * 5. **Dispatch classification**, which is allowed to fail — the same rule the mail path follows, and
+ *    for the same reason: a model that is briefly down must never take somebody's report with it.
+ *
+ * The count bound is checked in both places on purpose. The handler's is what keeps the decode
+ * bounded; this one is what keeps the bound true for any caller that reaches this function directly,
+ * which is every test and every future transport.
+ */
+/** What a submission produced. */
+export interface SubmitOutcome {
+    /** The thread it landed in — new, or the one it continued. */
+    threadId: string;
+    /** The message row it created. */
+    messageId: string;
+    /** Whether it opened a thread rather than continuing one. */
+    newThread: boolean;
+    /** How many attachments were stored. */
+    attachments: number;
+    /** Whether a classification was dispatched. */
+    classifying: boolean;
+}
+/** One file a submitter attached, already decoded. */
+export interface SubmittedAttachment {
+    /** The filename as the client declared it. Untrusted; recorded, never honored. */
+    filename: string;
+    /** The MIME type as the client declared it, checked against the configured allowlist. */
+    contentType: string;
+    /** The bytes themselves. */
+    bytes: Uint8Array;
+}
+/** Everything a submission needs, all injectable — nothing below this reads a binding. */
+export interface SubmitDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** The resolved config. */
+    config: SupportConfig;
+    /**
+     * The effective taxonomy — the shipped defaults plus the adopter's, already merged.
+     *
+     * Taken as a dep rather than re-derived from `config.categories` here, because two resolutions of one
+     * taxonomy are two things free to disagree: the classifier parses against the capability's merged
+     * set, and a submitted claim validated against a differently-merged one would be accepted or refused
+     * on a vocabulary nothing else in the process uses.
+     */
+    categories: SupportCategories;
+    /** The R2 bucket attachments are written to. Absent means none are stored. */
+    bucket?: R2Bucket;
+    /** Whether the FTS5 index is composed. */
+    fts: boolean;
+    /**
+     * The submitter's account, by id. Returns null when `@pithy-sh/auth` is absent or the row is gone —
+     * both of which contradict the session that got here, so the caller treats it as a fault rather than
+     * as a supported state.
+     */
+    resolveAccount: (userId: string) => Promise<{
+        email: string;
+        name?: string;
+    } | null>;
+    /** Start a classification for a stored message. Allowed to fail and allowed to decline. */
+    dispatchClassify: (messageId: string) => Promise<boolean>;
+    /** The audit seam. */
+    emit: AuditEmit;
+    /** The request logger. */
+    log: Logger;
+    /** Generate a row id. */
+    newId: () => string;
+    /** Now. */
+    now: () => Date;
+}
+/** What the submitter sent, with the identity taken from the session rather than from the payload. */
+export interface SubmitInput {
+    /** The authenticated user id. **From `c.var.auth`, never from the body.** */
+    userId: string;
+    /** What the report is about. Becomes the thread's name, and the subject of every reply on it. */
+    subject: string;
+    /** The report itself, as the person wrote it. */
+    body: string;
+    /**
+     * What the submitter says this is about, from the app's own chooser. Their claim, not a
+     * classification — validated against the effective taxonomy, stored on the thread it opens, and never
+     * read by the classifier. Absent when the client offers no chooser, which stays the ordinary case.
+     *
+     * Accepted only on a submission that **opens** a thread; sending it with `threadId` is refused rather
+     * than ignored (see {@link checkDeclaredCategory}).
+     */
+    declaredCategory?: string;
+    /** Continue this thread instead of opening one. Refused unless it is this account's own app thread. */
+    threadId?: string;
+    /** The bounded context the app supplied. */
+    context?: SupportSubmissionContext;
+    /** The files attached, already decoded. */
+    attachments: readonly SubmittedAttachment[];
+}
+/**
+ * Mint an RFC 5322 message id for a submission.
+ *
+ * **Without this the conversation forks the first time the customer answers.** A reply to an app thread
+ * leaves by email carrying `In-Reply-To`, the customer's client puts that id in its `References`, and
+ * `parentCandidates` looks it up in `pithy_support_messages` — so a submission stored with no id of its
+ * own is a thread whose every answer opens a new one. The whole reason `mime/threading.ts` refuses to
+ * match on subject is that fragmented conversations are the failure mode worth engineering against.
+ *
+ * The domain comes from the inbox address, because that is the domain the reply will actually leave
+ * from; with no address configured there is no reply and therefore nothing to thread.
+ */
+export declare function submissionMessageId(messageId: string, inboxAddress: string | null | undefined): string | null;
+/** Take one in-app submission. */
+export declare function submitFeedback(deps: SubmitDeps, input: SubmitInput): Promise<SubmitOutcome>;
+//# sourceMappingURL=submit.d.ts.map

package/dist/submission/submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/submission/submit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAGnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAkB,KAAK,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAOxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,EAAE,EAAE,eAAe,CAAC;IACpB,2BAA2B;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;;;OAOG;IACH,UAAU,EAAE,iBAAiB,CAAC;IAC9B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0CAA0C;IAC1C,GAAG,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrF,2FAA2F;IAC3F,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,sBAAsB;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,WAAW;IACX,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,sGAAsG;AACtG,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,2CAA2C;IAC3C,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC7C;AA0MD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG7G;AAED,kCAAkC;AAClC,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAmKjG"}