@pithy-sh/support 0.1.1 → 0.1.3

package/dist/mime/sanitize.d.ts

@@ -0,0 +1,25 @@
+/** The largest sanitized body kept, **in bytes**. A dashboard rendering 5 MB of markup has already lost. */
+export declare const MAX_HTML_BYTES: number;
+/** Whether an `href` value is safe to keep. Relative URLs are fine; a bare scheme we do not know is not. */
+export declare function isSafeHref(value: string): boolean;
+/**
+ * Sanitize an HTML body for storage and later rendering.
+ *
+ * **Remote images are stripped, not merely sandboxed.** An `<img src="https://…">` in a support
+ * message is a read receipt: it tells the sender the exact moment somebody opened their mail and
+ * from which IP, and against a support inbox that is a reconnaissance tool for whoever is probing
+ * you. Every mail client blocks them by default and so does this. The `alt` text survives, so a
+ * screenshot that mattered leaves a visible trace rather than vanishing silently. The original is
+ * still in R2 if an operator genuinely needs to see it.
+ */
+export declare function sanitizeHtml(html: string): Promise<string>;
+/**
+ * Reduce HTML to readable plain text — the fallback when a message carried no text part.
+ *
+ * The classifier reads text, never markup: markup is tokens the adopter pays for that carry no
+ * meaning, and it is also an injection surface, since `<!-- ignore your instructions -->` reads
+ * exactly like prose to a model. Block-level tags become newlines so a paragraph structure survives
+ * the trip.
+ */
+export declare function htmlToText(html: string): Promise<string>;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/mime/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/mime/sanitize.ts"],"names":[],"mappings":"AAuEA,4GAA4G;AAC5G,eAAO,MAAM,cAAc,QAAa,CAAC;AAsCzC,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAmBjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ChE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwD9D"}

package/dist/mime/sanitize.js

@@ -0,0 +1,212 @@
+import { truncateToBytes } from "./truncate.js";
+//#region src/mime/sanitize.ts
+/**
+* HTML sanitization for inbound mail, through the runtime's own streaming parser.
+*
+* This capability ingests attacker-controlled content and a dashboard renders it. That is the
+* highest-risk sentence in the package, so the sanitizer is built on `HTMLRewriter` — workerd's real
+* HTML parser — rather than on regular expressions. A regex sanitizer is a list of the tricks its
+* author thought of; a parser-based one strips what the browser will actually see, which is the only
+* question that matters. It is also why this file has no dependencies: the safest HTML parser
+* available here already ships in the runtime.
+*
+* The policy is an **allowlist on both axes** — a small set of tags survives and a small set of
+* attributes survives — because a denylist is wrong the day a new attribute is invented, and a
+* support inbox will still be running then.
+*
+* `HTMLRewriter` is a Workers global, so it is touched only inside these functions. The module
+* imports cleanly under node (which the `.describe()` meta-test requires); its tests are
+* `.workers.test.ts`, running against the real parser rather than a stand-in for it.
+*/
+/**
+* Tags removed together with everything inside them.
+*
+* Two groups. The obvious executables (`script`, `iframe`, `object`, `embed`, `svg` — SVG is a
+* scripting context, not an image format), and the quiet ones: `style` because CSS can position an
+* invisible overlay over a real control, `link`/`base`/`meta` because they retarget or redirect the
+* whole document, `form` and its inputs because a phishing form rendered inside a trusted dashboard
+* is the most convincing phishing form there is, and `noscript`/`template` because their contents
+* are inert to the parser here and live to a browser later.
+*/
+const DROPPED_TAGS = /* @__PURE__ */ new Set([
+	"script",
+	"style",
+	"iframe",
+	"frame",
+	"frameset",
+	"object",
+	"embed",
+	"applet",
+	"link",
+	"meta",
+	"base",
+	"form",
+	"input",
+	"button",
+	"select",
+	"option",
+	"textarea",
+	"svg",
+	"math",
+	"noscript",
+	"template",
+	"title"
+]);
+/**
+* Attributes that survive, on any tag.
+*
+* Note what is absent and deliberate: `style` (see above), every `on*` handler, `srcset`/`ping`/
+* `formaction`, and every `data-*`. Nothing needs an allowlist entry to be dropped — anything not on
+* this list goes, which is what makes the policy hold against attributes that do not exist yet.
+*/
+const ALLOWED_ATTRIBUTES = /* @__PURE__ */ new Set([
+	"href",
+	"alt",
+	"title",
+	"colspan",
+	"rowspan",
+	"start",
+	"type",
+	"dir",
+	"lang"
+]);
+/** URL schemes a surviving `href` may use. Everything else — `javascript:`, `data:`, `vbscript:` — is dropped. */
+const ALLOWED_SCHEMES = [
+	"http:",
+	"https:",
+	"mailto:",
+	"tel:"
+];
+/** The largest sanitized body kept, **in bytes**. A dashboard rendering 5 MB of markup has already lost. */
+const MAX_HTML_BYTES = 524288;
+/**
+* Decode the character references a browser would decode before it resolves a scheme.
+*
+* `href="java
script:alert(1)"` is a `javascript:` URL to every browser: the parser decodes the
+* entity into a newline while reading the attribute, and the URL parser then strips it. A check that
+* reads the raw attribute sees `java
script:...`, whose first `#` looks like a fragment marker,
+* and waves it through as relative — which is exactly the bypass this function exists to remove.
+*
+* Numeric, hex, and the three named references that can hide a scheme. Deliberately not a general
+* entity decoder: this value is about to be compared against a scheme allowlist, and the only
+* question worth answering is whether decoding could turn it into something that *is* a scheme.
+*/
+function decodeReferences(value) {
+	return value.replace(/&#x([0-9a-f]+);?/gi, (_, hex) => codePoint(Number.parseInt(hex, 16))).replace(/&#(\d+);?/g, (_, dec) => codePoint(Number.parseInt(dec, 10))).replace(/:?/gi, ":").replace(/&newline;?/gi, "\n").replace(/&tab;?/gi, "	");
+}
+/**
+* One decoded character, or the replacement character when the reference names nothing.
+*
+* `String.fromCodePoint` throws a `RangeError` above U+10FFFF, and `�` in an `href` is a
+* string an attacker chooses. Unguarded it throws out of the attribute walk, rejects the whole
+* `sanitizeHtml` promise, and fails ingest for that message — a mailable denial of service in the
+* decoder that exists to make ingest safe. The HTML spec's own answer is U+FFFD, so this returns what
+* a browser would have shown: a character that names no scheme and so decides nothing.
+*/
+function codePoint(value) {
+	if (!Number.isInteger(value) || value < 0 || value > 1114111) return "�";
+	return value >= 55296 && value <= 57343 ? "�" : String.fromCodePoint(value);
+}
+/** Whether an `href` value is safe to keep. Relative URLs are fine; a bare scheme we do not know is not. */
+function isSafeHref(value) {
+	const trimmed = decodeReferences(value).replace(/[\u0000-\u0020]+/g, "").toLowerCase();
+	if (trimmed.length === 0) return false;
+	const colon = trimmed.indexOf(":");
+	if (colon === -1) return true;
+	if (colon > Math.min(...[
+		"/",
+		"?",
+		"#"
+	].map((char) => {
+		const index = trimmed.indexOf(char);
+		return index === -1 ? Number.POSITIVE_INFINITY : index;
+	}))) return true;
+	return ALLOWED_SCHEMES.includes(trimmed.slice(0, colon + 1));
+}
+/**
+* Sanitize an HTML body for storage and later rendering.
+*
+* **Remote images are stripped, not merely sandboxed.** An `<img src="https://…">` in a support
+* message is a read receipt: it tells the sender the exact moment somebody opened their mail and
+* from which IP, and against a support inbox that is a reconnaissance tool for whoever is probing
+* you. Every mail client blocks them by default and so does this. The `alt` text survives, so a
+* screenshot that mattered leaves a visible trace rather than vanishing silently. The original is
+* still in R2 if an operator genuinely needs to see it.
+*/
+async function sanitizeHtml(html) {
+	const sanitized = await new HTMLRewriter().onDocument({ comments(comment) {
+		comment.remove();
+	} }).on("*", { element(element) {
+		const tag = element.tagName.toLowerCase();
+		if (DROPPED_TAGS.has(tag)) {
+			element.remove();
+			return;
+		}
+		for (const pair of [...element.attributes]) {
+			const name = pair[0] ?? "";
+			const value = pair[1] ?? "";
+			const attribute = name.toLowerCase();
+			if (!ALLOWED_ATTRIBUTES.has(attribute)) {
+				element.removeAttribute(name);
+				continue;
+			}
+			if (attribute === "href" && !isSafeHref(value)) element.removeAttribute(name);
+		}
+		if (tag === "a" && element.getAttribute("href")) {
+			element.setAttribute("rel", "noopener noreferrer nofollow");
+			element.setAttribute("target", "_blank");
+		}
+	} }).transform(new Response(html)).text();
+	return truncateToBytes(sanitized, MAX_HTML_BYTES);
+}
+/**
+* Reduce HTML to readable plain text — the fallback when a message carried no text part.
+*
+* The classifier reads text, never markup: markup is tokens the adopter pays for that carry no
+* meaning, and it is also an injection surface, since `<!-- ignore your instructions -->` reads
+* exactly like prose to a model. Block-level tags become newlines so a paragraph structure survives
+* the trip.
+*/
+async function htmlToText(html) {
+	const parts = [];
+	let suppressed = 0;
+	await new HTMLRewriter().onDocument({
+		comments(comment) {
+			comment.remove();
+		},
+		text(chunk) {
+			if (suppressed === 0) parts.push(chunk.text);
+		}
+	}).on("*", { element(element) {
+		const tag = element.tagName.toLowerCase();
+		if (DROPPED_TAGS.has(tag)) {
+			element.remove();
+			suppressed += 1;
+			try {
+				element.onEndTag(() => {
+					suppressed -= 1;
+				});
+			} catch {
+				suppressed -= 1;
+			}
+			return;
+		}
+		if ([
+			"p",
+			"div",
+			"br",
+			"tr",
+			"li",
+			"h1",
+			"h2",
+			"h3",
+			"h4",
+			"h5",
+			"h6",
+			"blockquote"
+		].includes(tag)) parts.push("\n");
+	} }).transform(new Response(html)).text();
+	return parts.join("").replace(/[\t\r ]+/g, " ").replace(/ ?\n ?/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+//#endregion
+export { MAX_HTML_BYTES, htmlToText, isSafeHref, sanitizeHtml };

package/dist/mime/threading.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RFC 5322 threading — turning `Message-ID`, `In-Reply-To`, and `References` into a conversation.
+ *
+ * **Threading is done on ids, never on the subject.** Subject matching is what makes two unrelated
+ * people who both wrote "Refund" land in one thread, and it is what splits a real conversation the
+ * moment somebody's client localizes `Re:` to `Aw:` or `Antw:`. The headers exist precisely so this
+ * does not have to be guessed, and every mail client sets them.
+ *
+ * The chain is tried in the order that goes from most precise to least: `In-Reply-To` names exactly
+ * one message, so it is asked first; `References` is the whole ancestry, so it is the fallback for a
+ * client that dropped `In-Reply-To` or a reply to a message that reached us out of order. Reading
+ * `References` **newest-first** matters — the last entry is the nearest ancestor, and starting at the
+ * root would attach a reply to the top of a long thread rather than to the message it answers.
+ */
+/** The longest `References` chain kept. Bounded because the header is attacker-controlled and unbounded by spec. */
+export declare const MAX_REFERENCES = 50;
+/**
+ * Strip the angle brackets from a message id and bound it.
+ *
+ * Stored without brackets so a lookup is plain equality: the brackets are transport syntax, and one
+ * path storing `<a@b>` while another queries `a@b` is a threading bug that only shows up on replies.
+ */
+export declare function normalizeMessageId(value: string | null | undefined): string | undefined;
+/**
+ * Parse a `References` (or `In-Reply-To`) header into ids, oldest first, deduplicated and bounded.
+ *
+ * `postal-mime` hands `references` back as the raw header string, so the splitting is ours. Angle
+ * brackets are the delimiter when they are present and whitespace is the fallback when they are not,
+ * because a malformed header from a hand-rolled sender is a normal input here.
+ *
+ * **When the chain is over the cap, the OLDEST entries are dropped, not the newest.** That direction
+ * is the whole point: `parentCandidates` reads this list from the newest end backwards, because the
+ * nearest ancestor is the message a reply actually answers. Capping from the other end would discard
+ * exactly the ids the lookup wants first and keep the ones it would reach last — so a long thread
+ * would silently stop threading on `References` and fall back to whatever `In-Reply-To` happened to
+ * survive. Same rule `buildReferencesHeader` follows on the way out, and RFC 5322 §3.6.4 says to trim
+ * this end for the same reason.
+ */
+export declare function parseReferences(value: string | null | undefined): string[];
+/**
+ * The ids to look a parent up by, most precise first.
+ *
+ * The order is the whole content of this function: `In-Reply-To`, then `References` from the newest
+ * entry backwards. A caller resolves the first one it recognizes and stops.
+ */
+export declare function parentCandidates(inReplyTo: string | undefined, references: readonly string[]): string[];
+/**
+ * Build the `References` header value for an outgoing reply.
+ *
+ * RFC 5322 §3.6.4: a reply's `References` is the parent's `References` followed by the parent's
+ * `Message-ID`. Getting this wrong is not cosmetic — it is the difference between the customer
+ * seeing one conversation and seeing a new mail every time somebody answers them, which is the
+ * single most visible way a support inbox looks broken from the outside. It is also the reason
+ * replying belongs in the Worker rather than in a dashboard: only the Worker holds the chain.
+ *
+ * The result is bracketed and space-separated, ready to be a header value, and bounded from the
+ * *front* — RFC 5322 says to drop the oldest entries when a chain has to be trimmed, because the
+ * recent ones are what a client threads on.
+ */
+export declare function buildReferencesHeader(parentReferences: readonly string[], parentMessageId?: string): string;
+/**
+ * Mint a `Message-ID` for an outgoing reply.
+ *
+ * Ours to generate, because a message we send has to be nameable by the customer's own reply — their
+ * client will put this value in its `In-Reply-To`, and that is how the answer comes back to the same
+ * thread. The domain half is taken from the address it is sent as, so the id is plausible to a
+ * receiving spam filter rather than pointing at a domain we do not control.
+ */
+export declare function mintMessageId(fromAddress: string, uuid: string): string;
+/**
+ * The subject line for a reply — `Re: ` prefixed exactly once.
+ *
+ * Match `Re:` case-insensitively and allow the bracketed count some clients add (`Re[2]:`), so
+ * answering a long thread does not build `Re: Re: Re: Re:`. Non-English prefixes are deliberately
+ * left alone: they are unbounded in practice, and a stray `Aw: Re:` is cosmetic, while stripping a
+ * word that happened to look like a prefix would change what the customer wrote.
+ */
+export declare function replySubject(subject: string): string;
+//# sourceMappingURL=threading.d.ts.map

package/dist/mime/threading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threading.d.ts","sourceRoot":"","sources":["../../src/mime/threading.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,oHAAoH;AACpH,eAAO,MAAM,cAAc,KAAK,CAAC;AAKjC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAW1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAGvG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAU3G;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/mime/threading.js

@@ -0,0 +1,111 @@
+//#region src/mime/threading.ts
+/**
+* RFC 5322 threading — turning `Message-ID`, `In-Reply-To`, and `References` into a conversation.
+*
+* **Threading is done on ids, never on the subject.** Subject matching is what makes two unrelated
+* people who both wrote "Refund" land in one thread, and it is what splits a real conversation the
+* moment somebody's client localizes `Re:` to `Aw:` or `Antw:`. The headers exist precisely so this
+* does not have to be guessed, and every mail client sets them.
+*
+* The chain is tried in the order that goes from most precise to least: `In-Reply-To` names exactly
+* one message, so it is asked first; `References` is the whole ancestry, so it is the fallback for a
+* client that dropped `In-Reply-To` or a reply to a message that reached us out of order. Reading
+* `References` **newest-first** matters — the last entry is the nearest ancestor, and starting at the
+* root would attach a reply to the top of a long thread rather than to the message it answers.
+*/
+/** The longest `References` chain kept. Bounded because the header is attacker-controlled and unbounded by spec. */
+const MAX_REFERENCES = 50;
+/** The longest single message id kept, after unwrapping. Anything longer is not an id a client produced. */
+const MAX_ID_LENGTH = 512;
+/**
+* Strip the angle brackets from a message id and bound it.
+*
+* Stored without brackets so a lookup is plain equality: the brackets are transport syntax, and one
+* path storing `<a@b>` while another queries `a@b` is a threading bug that only shows up on replies.
+*/
+function normalizeMessageId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim().replace(/^<+/, "").replace(/>+$/, "").trim();
+	if (trimmed.length === 0 || trimmed.length > MAX_ID_LENGTH) return void 0;
+	return /\s/.test(trimmed) ? void 0 : trimmed;
+}
+/**
+* Parse a `References` (or `In-Reply-To`) header into ids, oldest first, deduplicated and bounded.
+*
+* `postal-mime` hands `references` back as the raw header string, so the splitting is ours. Angle
+* brackets are the delimiter when they are present and whitespace is the fallback when they are not,
+* because a malformed header from a hand-rolled sender is a normal input here.
+*
+* **When the chain is over the cap, the OLDEST entries are dropped, not the newest.** That direction
+* is the whole point: `parentCandidates` reads this list from the newest end backwards, because the
+* nearest ancestor is the message a reply actually answers. Capping from the other end would discard
+* exactly the ids the lookup wants first and keep the ones it would reach last — so a long thread
+* would silently stop threading on `References` and fall back to whatever `In-Reply-To` happened to
+* survive. Same rule `buildReferencesHeader` follows on the way out, and RFC 5322 §3.6.4 says to trim
+* this end for the same reason.
+*/
+function parseReferences(value) {
+	if (typeof value !== "string") return [];
+	const bracketed = [...value.matchAll(/<([^<>]+)>/g)].map((match) => match[1] ?? "");
+	const candidates = bracketed.length > 0 ? bracketed : value.split(/\s+/);
+	const seen = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		const id = normalizeMessageId(candidate);
+		if (id) seen.add(id);
+	}
+	const ids = [...seen];
+	return ids.length > 50 ? ids.slice(ids.length - 50) : ids;
+}
+/**
+* The ids to look a parent up by, most precise first.
+*
+* The order is the whole content of this function: `In-Reply-To`, then `References` from the newest
+* entry backwards. A caller resolves the first one it recognizes and stops.
+*/
+function parentCandidates(inReplyTo, references) {
+	const ordered = [...inReplyTo ? [inReplyTo] : [], ...[...references].reverse()];
+	return [...new Set(ordered)];
+}
+/**
+* Build the `References` header value for an outgoing reply.
+*
+* RFC 5322 §3.6.4: a reply's `References` is the parent's `References` followed by the parent's
+* `Message-ID`. Getting this wrong is not cosmetic — it is the difference between the customer
+* seeing one conversation and seeing a new mail every time somebody answers them, which is the
+* single most visible way a support inbox looks broken from the outside. It is also the reason
+* replying belongs in the Worker rather than in a dashboard: only the Worker holds the chain.
+*
+* The result is bracketed and space-separated, ready to be a header value, and bounded from the
+* *front* — RFC 5322 says to drop the oldest entries when a chain has to be trimmed, because the
+* recent ones are what a client threads on.
+*/
+function buildReferencesHeader(parentReferences, parentMessageId) {
+	const chain = [...parentReferences.filter((id) => id !== parentMessageId), ...parentMessageId ? [parentMessageId] : []];
+	const deduped = [...new Set(chain)];
+	return (deduped.length > 50 ? deduped.slice(deduped.length - 50) : deduped).map((id) => `<${id}>`).join(" ");
+}
+/**
+* Mint a `Message-ID` for an outgoing reply.
+*
+* Ours to generate, because a message we send has to be nameable by the customer's own reply — their
+* client will put this value in its `In-Reply-To`, and that is how the answer comes back to the same
+* thread. The domain half is taken from the address it is sent as, so the id is plausible to a
+* receiving spam filter rather than pointing at a domain we do not control.
+*/
+function mintMessageId(fromAddress, uuid) {
+	return `${uuid}@${fromAddress.slice(fromAddress.lastIndexOf("@") + 1) || "localhost"}`;
+}
+/**
+* The subject line for a reply — `Re: ` prefixed exactly once.
+*
+* Match `Re:` case-insensitively and allow the bracketed count some clients add (`Re[2]:`), so
+* answering a long thread does not build `Re: Re: Re: Re:`. Non-English prefixes are deliberately
+* left alone: they are unbounded in practice, and a stray `Aw: Re:` is cosmetic, while stripping a
+* word that happened to look like a prefix would change what the customer wrote.
+*/
+function replySubject(subject) {
+	const trimmed = subject.trim();
+	return /^re(\[\d+\])?:/i.test(trimmed) ? trimmed : `Re: ${trimmed}`;
+}
+//#endregion
+export { MAX_REFERENCES, buildReferencesHeader, mintMessageId, normalizeMessageId, parentCandidates, parseReferences, replySubject };

package/dist/mime/truncate.d.ts

@@ -0,0 +1,17 @@
+/** How many bytes this string occupies as UTF-8. */
+export declare function byteLength(value: string): number;
+/**
+ * `value`, cut to at most `maxBytes` UTF-8 bytes, never mid-code-point.
+ *
+ * **Binary search, because the obvious loop is quadratic.** Walking down one code unit at a time and
+ * re-encoding the prefix each step is O(n) encodes of O(n) bytes, and the starting point makes it
+ * worse: `maxBytes` *code units* can be four times `maxBytes` *bytes*, so multi-byte text starts far
+ * above the answer and decrements toward it. Measured on the real constants, a 400k-character CJK
+ * body took 174,763 iterations and about three minutes of CPU — inside an `email()` handler, which
+ * the runtime kills long before that, so the message was never stored and every redelivery hit the
+ * same wall. A size bound that loses the message is worse than no bound.
+ *
+ * The search runs over `[0, min(length, maxBytes)]`: `maxBytes` code units is an upper bound because
+ * every code unit is at least one byte, and the predicate is monotone, so O(log n) encodes settle it.
+ */ export declare function truncateToBytes(value: string, maxBytes: number): string;
+//# sourceMappingURL=truncate.d.ts.map

package/dist/mime/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/mime/truncate.ts"],"names":[],"mappings":"AAmBA,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;GAaG,CAAC,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiB3E"}

package/dist/mime/truncate.js

@@ -0,0 +1,47 @@
+//#region src/mime/truncate.ts
+/**
+* Truncation that counts **bytes**, because the limits it serves are byte limits.
+*
+* `String.prototype.slice` counts UTF-16 code units, so a bound written as "256 KB" admits 256 K
+* *characters* — three times that in bytes for CJK, four for most emoji. The bounds in this package
+* exist to keep a row under D1's 2,000,000-byte ceiling, and a character-counted bound does not do
+* that: a large CJK message sails through every check and then fails the insert, at which point the
+* inbound handler swallows the error and the customer's mail is gone. Counting the thing the limit is
+* about is the whole fix.
+*
+* Truncation lands on a code-point boundary, so the result is never a lone surrogate — which would be
+* invalid text in the database and could break a JSON encode downstream.
+*/
+const encoder = new TextEncoder();
+/** How many bytes this string occupies as UTF-8. */
+function byteLength(value) {
+	return encoder.encode(value).byteLength;
+}
+/**
+* `value`, cut to at most `maxBytes` UTF-8 bytes, never mid-code-point.
+*
+* **Binary search, because the obvious loop is quadratic.** Walking down one code unit at a time and
+* re-encoding the prefix each step is O(n) encodes of O(n) bytes, and the starting point makes it
+* worse: `maxBytes` *code units* can be four times `maxBytes` *bytes*, so multi-byte text starts far
+* above the answer and decrements toward it. Measured on the real constants, a 400k-character CJK
+* body took 174,763 iterations and about three minutes of CPU — inside an `email()` handler, which
+* the runtime kills long before that, so the message was never stored and every redelivery hit the
+* same wall. A size bound that loses the message is worse than no bound.
+*
+* The search runs over `[0, min(length, maxBytes)]`: `maxBytes` code units is an upper bound because
+* every code unit is at least one byte, and the predicate is monotone, so O(log n) encodes settle it.
+*/ function truncateToBytes(value, maxBytes) {
+	if (maxBytes <= 0) return "";
+	if (byteLength(value) <= maxBytes) return value;
+	let low = 0;
+	let high = Math.min(value.length, maxBytes);
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (byteLength(value.slice(0, mid)) <= maxBytes) low = mid;
+		else high = mid - 1;
+	}
+	const cut = value.slice(0, low);
+	return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+}
+//#endregion
+export { byteLength, truncateToBytes };

package/dist/provision/provisionSupport.d.ts

@@ -0,0 +1,158 @@
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+/**
+ * The provisioning orchestration for the support capability — the live counterpart to
+ * `pithy add support`'s config wiring.
+ *
+ * Three things have to exist before a support inbox works, and none of them can be a binding an
+ * adopter hand-writes: the R2 bucket attachments and raw messages land in, the prebuilt classification
+ * worker per environment, and — the one that actually delivers the mail — an Email Routing rule
+ * pointing the support address at the app worker.
+ *
+ * The live Cloudflare/wrangler steps sit behind the {@link SupportProvisioner} seam, so the
+ * orchestration (order, idempotency, per-env fan-out) is unit-tested without touching Cloudflare.
+ * Every step is idempotent; re-running is a no-op.
+ *
+ * ## The routing rule is opt-in, and that is a safety decision
+ *
+ * `ensureRoutingRule` returns `skipped: true` when no routing config is supplied, exactly as
+ * `@pithy-sh/email`'s does — because **enabling Email Routing on a zone points its MX at Cloudflare.**
+ * Creating a rule on the wrong zone would move an adopter's real inbound mail off their existing
+ * provider, which is not a mistake a provisioning command gets to make on their behalf. So the zone,
+ * the address, and the target worker are all explicit flags, and a project that has not decided yet
+ * provisions everything else and adds the rule later.
+ *
+ * The rule name is `<project>-global-support-inbound`, deliberately distinct from `@pithy-sh/email`'s
+ * `<project>-global-email-bounce`. Idempotency in `ensureWorkerRoute` keys on the rule *name*, so
+ * sharing one would make whichever capability provisioned second silently believe its rule already
+ * existed — and the project segment is what stops two Pithy projects on one zone doing the same to
+ * each other, with the loser's customer mail delivered to the winner's Worker.
+ */
+/**
+ * The name of the Email Routing rule this capability creates, for one project. Distinct from the
+ * bounce handler's, and `global` in the environment slot because there is one rule per zone: the
+ * environments are separated by which app Worker the rule is pointed at, not by the rule.
+ *
+ * **Still on the generic composer**, and deliberately: an Email Routing rule is not a namespace
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for, and the facade exists so a
+ * kind of thing brings its own number rather than borrowing one. It takes the conservative default
+ * until that namespace lands — the same call `@pithy-sh/email`'s bounce rule makes.
+ */
+export declare function supportRoutingRuleName(project: string): string;
+/**
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
+ * through core's naming facade under the **`worker`** namespace, so it is measured against a Worker
+ * script's 63 and the environment is validated on the way through. One source, so the name the CLI
+ * audits and deletes under cannot drift from the name it deploys under.
+ */
+export declare function supportWorkerName(project: string, env: ManagedEnvironment): string;
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface SupportProvisioner {
+    /**
+     * Verify account prerequisites before any resource is created — most importantly a registered
+     * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting worker.
+     */
+    preflight(): Promise<void>;
+    /**
+     * Create (or reuse) the R2 bucket attachments and raw messages live in. Idempotent.
+     *
+     * Returns `skipped: true` when the capability is configured with attachments off — a bucket nobody
+     * writes to is a resource an adopter did not ask for.
+     */
+    ensureBucket(): Promise<{
+        bucket: string;
+        created: boolean;
+        skipped: boolean;
+    }>;
+    /** Deploy the prebuilt classification worker for this environment. */
+    deployWorker(env: ManagedEnvironment): Promise<void>;
+    /**
+     * Create or drop the full-text index in this environment's app database, to match `search.fts`.
+     *
+     * A provisioning step rather than a migration, because the index is **derived** — every row in it
+     * comes from `pithy_support_messages` and `reindexThread` rebuilds it on demand. That is the line a
+     * migration is for: schema whose loss loses data. Keeping it here is also what makes the flag safe
+     * to toggle at all, since a config-conditional migration removed from the set is corruption to
+     * Kysely and blocks `pithy migrate` for every capability sharing the database.
+     */
+    ensureSearchIndex(env: ManagedEnvironment): Promise<{
+        created: boolean;
+        dropped: boolean;
+    }>;
+    /**
+     * Ensure the inbound Email Routing rule that delivers the support address to the app worker.
+     * Idempotent, keyed on the rule name. Returns `skipped: true` when no routing config was supplied.
+     */
+    ensureRoutingRule(): Promise<{
+        created: boolean;
+        skipped: boolean;
+    }>;
+}
+/** What provisioning produced. */
+export interface SupportProvisionResult {
+    /** The R2 bucket, and whether it had to be created. */
+    bucket: {
+        bucket: string;
+        created: boolean;
+        skipped: boolean;
+    };
+    /** The environments a classification worker was deployed for. */
+    environments: ManagedEnvironment[];
+    /** What the full-text index did, per environment — created, dropped, or already correct. */
+    search: Array<{
+        env: ManagedEnvironment;
+        created: boolean;
+        dropped: boolean;
+    }>;
+    /** Whether the inbound routing rule was created, already present, or skipped. */
+    routing: {
+        created: boolean;
+        skipped: boolean;
+    };
+}
+/**
+ * Provision the support infrastructure.
+ *
+ * The order matters and is the inverse of how it fails: the bucket exists before a worker that could
+ * write to it, and **the routing rule is last** — creating it first would start delivering mail to a
+ * Worker whose classification host is not deployed yet, which is a window where real customer
+ * messages arrive and stay `uncategorized` with nothing to say why.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export declare function provisionSupport(provisioner: SupportProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<SupportProvisionResult>;
+/** The teardown seam — the inverse of {@link SupportProvisioner}. Every step idempotent. */
+export interface SupportDeprovisioner {
+    /** Delete the env's classification worker. Idempotent. */
+    deleteWorker(env: ManagedEnvironment): Promise<void>;
+    /** Remove the inbound routing rule, so mail stops being delivered here. Idempotent. */
+    removeRoutingRule(): Promise<{
+        removed: boolean;
+    }>;
+    /**
+     * Delete the R2 bucket **and everything in it** — every attachment and every raw message an adopter's
+     * customers ever sent. Destructive, so the orchestration only calls it when explicitly asked.
+     */
+    deleteBucket(): Promise<void>;
+}
+/** Teardown options. By default the bucket is **kept**: it holds correspondence, not cache. */
+export interface SupportDeprovisionOptions {
+    /** Also delete the R2 bucket and its contents. Off by default. */
+    deleteStorage?: boolean;
+}
+/**
+ * Tear down the support infrastructure, reversing {@link provisionSupport}.
+ *
+ * The routing rule goes **first**, and that ordering is the whole point: stop new mail arriving before
+ * removing the workers that would have handled it, or messages land in a Worker with no classification
+ * host during the teardown. Stored correspondence is preserved unless explicitly requested — losing an
+ * adopter's support history to a teardown flag would be unrecoverable.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export declare function deprovisionSupport(deprovisioner: SupportDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: SupportDeprovisionOptions): Promise<void>;
+//# sourceMappingURL=provisionSupport.d.ts.map