@pithy-sh/support 0.1.1 → 0.1.3

package/dist/submission/encoding.js

@@ -0,0 +1,55 @@
+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` materialises 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,71 @@
+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,46 @@
+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,152 @@
+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` materialises 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"}

package/dist/submission/submit.js

@@ -0,0 +1,319 @@
+import { SupportInvalidCategoryError, SupportNotFoundError, SupportRejectedError } from "../error/errors.js";
+import { categoryEnum } from "../data/categories.js";
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread, UNCLASSIFIED } from "../data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { attachmentKey, putAttachment, sha256Hex } from "../attachment/store.js";
+import { SupportAuditActions } from "../audit/actions.js";
+import { indexMessage } from "../store/search.js";
+import { safeFilename } from "../mime/parse.js";
+import { checkAccountRate, checkAttachment } from "./guard.js";
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+//#region src/submission/submit.ts
+/** Record a refusal. Never throws — a guard decision must not become a 500 on top of a 429. */
+async function auditRejection(deps, reason, detail, userId) {
+	try {
+		await deps.emit({
+			action: SupportAuditActions.submissionRejected,
+			outcome: "denied",
+			severity: "warning",
+			actorType: "user",
+			actorId: userId,
+			resourceType: "support_inbox",
+			metadata: {
+				reason,
+				channel: "app"
+			}
+		});
+		deps.log.warn("support submission refused", {
+			reason,
+			detail,
+			userId
+		});
+	} catch (error) {
+		deps.log.warn("support submission rejection audit dropped", {
+			reason,
+			detail,
+			error
+		});
+	}
+}
+/**
+* Resolve the thread a submission continues.
+*
+* **Both conditions, and a 404 rather than a 403 when either fails.** The thread must be this
+* account's and it must be an app thread: a 403 would confirm that the id names a real conversation,
+* which on an inbox of other people's correspondence is the disclosure the check exists to prevent —
+* so an id belonging to somebody else is indistinguishable from one belonging to nobody.
+*
+* An `email` thread is excluded even when it carries this account's `userId`, and that exclusion is
+* the point rather than an oversight: that link was matched from an address in a header nobody proved,
+* so treating it as ownership would let whoever currently holds an address read a conversation that
+* merely *claims* to be theirs.
+*/
+async function resolveOwnThread(db, threadId, userId) {
+	const thread = await db.selectFrom(SUPPORT_THREADS_TABLE).select(["id"]).where("id", "=", threadId).where("userId", "=", userId).where("channel", "=", "app").executeTakeFirst();
+	if (!thread) throw new SupportNotFoundError({ detail: `no app thread ${threadId} owned by ${userId}` });
+	return thread;
+}
+/**
+* Check a submitter's declared category, before anything else and before any I/O.
+*
+* **An undeclared key is refused, never stored and never downgraded.** Storing it would make
+* `declared_category` a client-writable vocabulary: one client shipping `Billing` or `billng` and the
+* console's filter silently misses those threads forever, while the inbox grows a long tail of one-off
+* keys nobody declared. Downgrading to `uncategorized` is the worse of the two remaining options,
+* because it makes a broken chooser indistinguishable from a submitter who genuinely chose nothing —
+* the exact collapse this column exists to prevent, arrived at from the other side.
+*
+* It is refused rather than tolerated **because the writer can be fixed.** `classifyMessage` falls back
+* to `uncategorized` on a label the model invented, and that is right there: a model cannot be told it
+* was wrong at the call site. A client can, and a 400 is how it gets told — the chooser was built from
+* a taxonomy the adopter declared, so a value outside it is that client's bug and should be loud.
+*
+* **A category may not ride along with a `threadId`.** A thread already carries what it was filed
+* under, and a second, later claim has no honest meaning: ignoring it is a chooser that does nothing —
+* which is the whole defect this seam exists to close — and honoring it would let a follow-up rewrite
+* the premise a conversation was opened on, the way `subject` deliberately cannot. So it is refused,
+* loudly, and a chooser stays what it is: something offered on the form that opens a request.
+*
+* **Nothing the submitter wrote reaches `message`.** The offending value goes in `detail`, which the
+* HTTP codec strips — this capability's whole input is text somebody else chose, and an error that
+* echoed it back would make the error channel a reflection surface.
+*/
+function checkDeclaredCategory(deps, input) {
+	const declared = input.declaredCategory;
+	if (declared === void 0) return;
+	if (input.threadId !== void 0) throw new ValidationError({
+		message: "A category is chosen when a request is opened, not on a later message.",
+		action: "Send the category with the first message, or leave it off to continue the conversation.",
+		detail: `submission declared a category alongside threadId ${input.threadId}`
+	});
+	if (!categoryEnum(deps.categories).safeParse(declared).success) throw new SupportInvalidCategoryError({
+		message: "That is not a category this app offers.",
+		action: "Choose one of the categories the app declares, or send the request without one.",
+		detail: `submitted category ${JSON.stringify(declared)} is not in the effective taxonomy (${Object.keys(deps.categories).join(", ")})`
+	});
+}
+/** How many columns one `pithy_support_attachments` row binds — derived, so a new column re-chunks. */
+const SUPPORT_ATTACHMENT_COLUMNS = Object.keys(SupportAttachment.shape).length;
+/**
+* Check every attachment before one byte is written.
+*
+* All-or-nothing, and refused rather than skipped — the opposite of the mail path, and the difference
+* is who is on the other end. An oversize part of an email is dropped because the sender is gone and
+* the message is still worth keeping; a submitter is right there, holding the screenshot that is the
+* most valuable thing the report carries, and silently storing the report without it means the first
+* reply asks for a file they believed they had already sent.
+*/
+function checkAttachments(deps, attachments) {
+	const bounds = deps.config.submission.attachments;
+	if (attachments.length === 0) return;
+	if (!bounds.enabled) throw new ValidationError({
+		message: "This app does not accept attachments on a support request.",
+		action: "Send the report without a file, and describe what you would have attached.",
+		detail: "submission.attachments.enabled is false"
+	});
+	if (attachments.length > bounds.maxCount) throw new ValidationError({
+		message: `A support request may carry at most ${bounds.maxCount} attachments.`,
+		action: `Send at most ${bounds.maxCount} files.`,
+		detail: `submission declared ${attachments.length} attachments, over the ${bounds.maxCount} bound`
+	});
+	for (const attachment of attachments) {
+		const verdict = checkAttachment(deps.config.submission, {
+			contentType: attachment.contentType,
+			bytes: attachment.bytes.byteLength
+		});
+		if (verdict.accepted) continue;
+		throw new ValidationError({
+			message: verdict.reason === "attachment_too_large" ? `An attachment may be at most ${bounds.maxBytes} bytes.` : "That kind of file cannot be attached to a support request.",
+			action: verdict.reason === "attachment_too_large" ? "Attach a smaller file." : `Attach one of: ${bounds.allowedContentTypes.join(", ")}.`,
+			detail: verdict.detail
+		});
+	}
+}
+/** Store the checked attachments. Returns how many rows were written. */
+async function storeAttachments(deps, attachments, threadId, messageId, now) {
+	const bucket = deps.bucket;
+	if (attachments.length === 0) return 0;
+	if (!bucket) {
+		deps.log.warn("support submission attachments dropped — no bucket bound", {
+			threadId,
+			messageId
+		});
+		return 0;
+	}
+	const rows = [];
+	for (const attachment of attachments) {
+		const id = deps.newId();
+		const key = attachmentKey(threadId, id);
+		await putAttachment(bucket, key, attachment.bytes);
+		rows.push({
+			id,
+			messageId,
+			threadId,
+			filename: safeFilename(attachment.filename),
+			contentType: attachment.contentType,
+			size: attachment.bytes.byteLength,
+			sha256: await sha256Hex(attachment.bytes),
+			storageKey: key,
+			contentId: null,
+			inline: false,
+			createdAt: now
+		});
+	}
+	const encoded = rows.map((row) => SupportAttachment.encode(row));
+	for (const chunk of chunkRowsByBoundParameters(encoded, SUPPORT_ATTACHMENT_COLUMNS)) await deps.db.insertInto(SUPPORT_ATTACHMENTS_TABLE).values(chunk).execute();
+	return rows.length;
+}
+/**
+* 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.
+*/
+function submissionMessageId(messageId, inboxAddress) {
+	const domain = inboxAddress?.split("@")[1];
+	return domain ? `${messageId}@${domain}` : null;
+}
+/** Take one in-app submission. */
+async function submitFeedback(deps, input) {
+	const now = deps.now();
+	checkDeclaredCategory(deps, input);
+	const account = await deps.resolveAccount(input.userId);
+	if (!account) throw new InternalError({
+		message: "Your account could not be read.",
+		action: "Retry, and contact support by email if it keeps happening.",
+		detail: `no pithy_auth_users row for authenticated user ${input.userId} — is @pithy-sh/auth composed on this Worker?`
+	});
+	const rate = await checkAccountRate(deps.db, deps.config.submission, {
+		userId: input.userId,
+		now
+	});
+	if (!rate.accepted) {
+		await auditRejection(deps, rate.reason, rate.detail, input.userId);
+		throw new SupportRejectedError({
+			message: "You have sent too many support requests recently.",
+			action: "Wait an hour and try again, or reply to the email on an existing request.",
+			detail: rate.detail
+		});
+	}
+	checkAttachments(deps, input.attachments);
+	const existing = input.threadId ? await resolveOwnThread(deps.db, input.threadId, input.userId) : void 0;
+	const threadId = existing?.id ?? deps.newId();
+	const newThread = existing === void 0;
+	const messageId = deps.newId();
+	const inbox = deps.config.reply.replyToAddress ?? deps.config.inboundAddresses[0] ?? null;
+	const message = {
+		id: messageId,
+		threadId,
+		direction: "inbound",
+		channel: "app",
+		submittedByUserId: input.userId,
+		context: input.context ?? null,
+		mimeMessageId: submissionMessageId(messageId, inbox),
+		mimeInReplyTo: null,
+		mimeReferences: null,
+		fromAddress: account.email,
+		fromName: account.name ?? null,
+		toAddress: inbox,
+		subject: input.subject,
+		textBody: input.body,
+		htmlBody: null,
+		emailJobId: null,
+		rawKey: null,
+		rawBytes: null,
+		receivedAt: now,
+		createdAt: now
+	};
+	await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
+	try {
+		if (newThread) {
+			const thread = {
+				id: threadId,
+				channel: "app",
+				inboxAddress: inbox,
+				subject: input.subject,
+				fromAddress: account.email,
+				fromName: account.name ?? null,
+				senderAuthenticated: true,
+				userId: input.userId,
+				accountLinkSource: "session",
+				declaredCategory: input.declaredCategory ?? null,
+				...UNCLASSIFIED,
+				archived: false,
+				archivedAt: null,
+				archivedBy: null,
+				messageCount: 1,
+				firstMessageAt: now,
+				lastMessageAt: now,
+				createdAt: now,
+				updatedAt: now
+			};
+			await deps.db.insertInto(SUPPORT_THREADS_TABLE).values(SupportThread.encode(thread)).execute();
+		} else await deps.db.updateTable(SUPPORT_THREADS_TABLE).set((eb) => ({
+			messageCount: eb("messageCount", "+", 1),
+			lastMessageAt: now.getTime(),
+			updatedAt: now.getTime(),
+			archived: 0,
+			archivedAt: null,
+			archivedBy: null
+		})).where("id", "=", threadId).execute();
+	} catch (error) {
+		await deps.db.deleteFrom(SUPPORT_MESSAGES_TABLE).where("id", "=", messageId).execute().catch(() => {
+			deps.log.error("support submission orphaned — thread write failed and the message could not be removed", {
+				messageId,
+				threadId
+			});
+		});
+		throw error;
+	}
+	if (deps.fts) try {
+		await indexMessage(deps.db, {
+			threadId,
+			messageId,
+			subject: input.subject,
+			body: input.body
+		});
+	} catch (error) {
+		deps.log.warn("support submission not indexed", {
+			messageId,
+			error
+		});
+	}
+	let attachments = 0;
+	try {
+		attachments = await storeAttachments(deps, input.attachments, threadId, messageId, now);
+	} catch (error) {
+		deps.log.warn("support submission attachments not stored", {
+			messageId,
+			error
+		});
+	}
+	const classifying = deps.config.ai.enabled;
+	if (classifying) try {
+		await deps.dispatchClassify(messageId);
+	} catch (error) {
+		deps.log.warn("support submission classification dispatch failed", {
+			messageId,
+			error
+		});
+	}
+	return {
+		threadId,
+		messageId,
+		newThread,
+		attachments,
+		classifying
+	};
+}
+//#endregion
+export { submissionMessageId, submitFeedback };

package/dist/version.generated.d.ts

@@ -0,0 +1,5 @@
+/** This package's npm name — the join key against a release feed. */
+export declare const PACKAGE_NAME = "@pithy-sh/support";
+/** This package's version, stamped from its own package.json at generation time. */
+export declare const PACKAGE_VERSION = "0.1.3";
+//# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,sBAAsB,CAAC;AAEhD,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}