@pithy-sh/support 0.1.2 → 0.1.4

package/dist/link/sender.js

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_BILLING_SCOPE } from "../data/billingScope.js";
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+//#region src/link/sender.ts
+/** How many purchases a thread view carries. Enough to see the pattern, bounded so a whale is not a slow page. */
+const MAX_LINKED_PURCHASES = 25;
+/**
+* Resolve a sender address to a user id.
+*
+* **Exact match on the normalized address, and deliberately no case-insensitive fallback.** The
+* `email` column is indexed and unique, so this is one index seek; a `lower(email) = ?` fallback
+* would be a full table scan, and it would run for *every unknown sender* — which on a public
+* address means every piece of spam scanning the entire user table. Better Auth normalizes on its
+* own signup path, so the exact match is the case that actually occurs; an address stored with
+* capitals by some other route simply does not link, which costs a line of context rather than a
+* customer's request.
+*/
+async function resolveSenderUserId(d1, address) {
+	const normalized = parseAddress(address);
+	if (!normalized) return null;
+	try {
+		const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+		return (await authDatabase(d1).selectFrom("pithyAuthUsers").select(["id"]).where("email", "=", normalized).executeTakeFirst())?.id ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The address an operator's reply to an app thread will be sent to, or null when the account carries
+* nothing deliverable.
+*
+* Extracted rather than inlined because it is the one decision in {@link resolveSubmitterAccount} with
+* a wrong answer available, and inlining it puts that decision behind a guarded dynamic import where
+* no test can reach it.
+*
+* **`parseAddress` only, with no `normalizeAddress` fallback.** The fallback merely trims and
+* lowercases, so it would hand back an address this capability's own parser had just refused — and
+* this value becomes the thread's `fromAddress`, which `sendReply` enqueues an answer to. Returning
+* null makes an unparseable account the same hard fault as a missing one, which is what the caller
+* already does with it: refusing the submission beats accepting a report whose only reply address
+* cannot be delivered to.
+*/
+function submitterAddress(email) {
+	return email && parseAddress(email) || null;
+}
+/**
+* The account behind an authenticated submitter — resolved by id, never by an address.
+*
+* The inverse of {@link resolveSenderUserId}, and it exists because the in-app channel starts from the
+* opposite end: a session names a user id, and what the thread needs is the address a reply will go
+* back to. Deriving that from anything the client sent would hand a signed-in caller the ability to
+* point a support conversation — and every operator reply on it — at somebody else's mailbox.
+*
+* Returns null when `@pithy-sh/auth` is absent or the account is gone. A submission whose account
+* cannot be read is refused by the caller rather than stored with a guessed address: an app thread with
+* no working reply address is a report nobody can answer.
+*/
+async function resolveSubmitterAccount(d1, userId) {
+	try {
+		const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+		const { User } = await import("@pithy-sh/auth/src/data/betterAuth");
+		const row = await authDatabase(d1).selectFrom("pithyAuthUsers").selectAll().where("id", "=", userId).executeTakeFirst();
+		if (!row) return null;
+		const user = User.parse(row);
+		const email = submitterAddress(user.email);
+		if (!email) return null;
+		return {
+			email,
+			name: user.name,
+			emailVerified: user.emailVerified
+		};
+	} catch {
+		return null;
+	}
+}
+/** Read the account's own fields, when auth is composed. */
+async function resolveAccount(d1, address) {
+	try {
+		const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+		const { User } = await import("@pithy-sh/auth/src/data/betterAuth");
+		const row = await authDatabase(d1).selectFrom("pithyAuthUsers").selectAll().where("email", "=", address).executeTakeFirst();
+		if (!row) return null;
+		const user = User.parse(row);
+		return {
+			userId: user.id,
+			name: user.name,
+			emailVerified: user.emailVerified
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Read what the account bought, when payments is composed — **`user`-subject rows only**.
+*
+* Both halves of the pair, deliberately. Nothing in the kit keeps an organization id from equalling some
+* user's, so a filter on the id alone would eventually hand one holder's purchases to the other — which
+* is the whole reason payments made the holder a pair. See {@link SUPPORT_BILLING_SCOPE} for why the
+* type half is pinned to `user` rather than resolved.
+*/
+async function resolvePurchases(d1, userId) {
+	try {
+		const { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } = await import("@pithy-sh/payments/src/data/tables");
+		const { PaymentsPurchase } = await import("@pithy-sh/payments/src/data/purchase");
+		return (await paymentsDatabase(d1).selectFrom(PAYMENTS_PURCHASES_TABLE).selectAll().where("subjectType", "=", SUPPORT_BILLING_SCOPE).where("subjectId", "=", userId).orderBy("purchasedAt", "desc").limit(25).execute()).map((row) => {
+			const purchase = PaymentsPurchase.parse(row);
+			return {
+				id: purchase.id,
+				rail: purchase.rail,
+				productId: purchase.productId,
+				status: purchase.status,
+				environment: purchase.environment,
+				purchasedAt: purchase.purchasedAt,
+				expiresAt: purchase.expiresAt ?? null,
+				revokedAt: purchase.revokedAt ?? null
+			};
+		});
+	} catch {
+		return [];
+	}
+}
+/** Read what the account is entitled to, when payments is composed — **`user`-subject rows only**. */
+async function resolveLinkedEntitlements(d1, userId, now) {
+	try {
+		const { paymentsDatabase } = await import("@pithy-sh/payments/src/data/tables");
+		const { resolveEntitlements } = await import("@pithy-sh/payments/src/projection/resolve");
+		return await resolveEntitlements(paymentsDatabase(d1), {
+			subjectType: SUPPORT_BILLING_SCOPE,
+			subjectId: userId
+		}, now);
+	} catch {
+		return [];
+	}
+}
+/**
+* Everything the app already knows about a sender — read at thread-read time rather than stored.
+*
+* Derived, so it is always current: a customer who buys Pro an hour after writing in shows as
+* entitled the next time the thread is opened, with nothing to backfill and nothing to invalidate.
+* That is the same rule the classification follows, applied to the half of the model that lives in
+* somebody else's tables.
+*/
+async function resolveSenderContext(d1, address, now, options) {
+	const empty = {
+		authenticated: options.authenticated,
+		userId: null,
+		purchases: [],
+		entitlements: []
+	};
+	const normalized = parseAddress(address);
+	if (!normalized) return empty;
+	const account = await resolveAccount(d1, normalized);
+	if (!account) return empty;
+	if (!options.authenticated) return {
+		authenticated: false,
+		userId: account.userId,
+		name: account.name,
+		purchases: [],
+		entitlements: []
+	};
+	return provenContext(d1, account, now);
+}
+/**
+* The customer context behind a **session-proven** link, resolved from the user id itself.
+*
+* An app thread already holds the id its session proved, so re-deriving it from the thread's address
+* would be both a step backwards and a correctness bug: `resolveSenderUserId` matches the `email`
+* column exactly, and an account stored with capitals by some other route would silently resolve to
+* nobody — turning the one link that *is* certain into the one the console shows as unknown.
+*
+* Everything below the link degrades exactly as it does on the mail path: purchases and entitlements
+* are guarded dynamic imports and come back empty when `@pithy-sh/payments` is absent.
+*/
+async function resolveSubmitterContext(d1, userId, now) {
+	const account = await resolveSubmitterAccount(d1, userId);
+	if (!account) return {
+		authenticated: true,
+		userId,
+		purchases: [],
+		entitlements: []
+	};
+	return provenContext(d1, {
+		userId,
+		name: account.name,
+		emailVerified: account.emailVerified
+	}, now);
+}
+/** The proven half, shared by both entry points: the account, plus what it bought and what it holds. */
+async function provenContext(d1, account, now) {
+	const [purchases, entitlements] = await Promise.all([resolvePurchases(d1, account.userId), resolveLinkedEntitlements(d1, account.userId, now)]);
+	return {
+		authenticated: true,
+		userId: account.userId,
+		name: account.name,
+		emailVerified: account.emailVerified,
+		purchases,
+		entitlements
+	};
+}
+//#endregion
+export { MAX_LINKED_PURCHASES, resolveSenderContext, resolveSenderUserId, resolveSubmitterAccount, resolveSubmitterContext, submitterAddress };

package/dist/migrations/0001_threads.d.ts

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Migration } from "kysely/migration";
+/**
+ * The support inbox: threads, their messages, attachment metadata, the append-only classification
+ * history, and per-viewer flags.
+ *
+ * **The indexes are the point of this migration, not an afterthought.** The dashboard's entire
+ * interaction is "inbox, newest first, filtered by category and priority and archived" — a query
+ * workload, and one that is miserable to retrofit once a table has rows in production. So the two
+ * composite indexes the issue names are created here, in the first migration, alongside the tables.
+ *
+ * camelCase identifiers throughout; `CamelCasePlugin` snake-cases them in the DDL. `down` is the
+ * tested inverse — indexes first, then tables, children before parents.
+ *
+ * **No CHECK constraints, deliberately.** CLAUDE.md's rule is that one Zod schema per table is the
+ * entire table definition, and a CHECK mirroring a `z.enum` or a `SQLiteBoolean` is a second, partial
+ * copy of that definition — one that can drift from the schema and that SQLite cannot alter, so
+ * adding a priority level or a sentiment would mean a table rebuild rather than a one-line edit to
+ * the enum. Every value here reaches SQLite through `Schema.encode`, so the schema already refuses
+ * what a CHECK would have. The three bounds that were doing real work — both `confidence` ranges and
+ * the attachment `size` floor — moved into the schemas, which is where they belonged.
+ *
+ * A CHECK still earns its place for an invariant Zod genuinely cannot express: `@pithy-sh/ledger`
+ * constrains `held <= balance` across columns, which no per-field schema can state.
+ */
+export declare const support_0001_threads: Migration;
+//# sourceMappingURL=0001_threads.d.ts.map

package/dist/migrations/0001_threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0001_threads.d.ts","sourceRoot":"","sources":["../../src/migrations/0001_threads.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,EAAE,SA0QlC,CAAC"}

package/dist/migrations/0001_threads.js

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/migrations/0001_threads.ts
+/**
+* The support inbox: threads, their messages, attachment metadata, the append-only classification
+* history, and per-viewer flags.
+*
+* **The indexes are the point of this migration, not an afterthought.** The dashboard's entire
+* interaction is "inbox, newest first, filtered by category and priority and archived" — a query
+* workload, and one that is miserable to retrofit once a table has rows in production. So the two
+* composite indexes the issue names are created here, in the first migration, alongside the tables.
+*
+* camelCase identifiers throughout; `CamelCasePlugin` snake-cases them in the DDL. `down` is the
+* tested inverse — indexes first, then tables, children before parents.
+*
+* **No CHECK constraints, deliberately.** CLAUDE.md's rule is that one Zod schema per table is the
+* entire table definition, and a CHECK mirroring a `z.enum` or a `SQLiteBoolean` is a second, partial
+* copy of that definition — one that can drift from the schema and that SQLite cannot alter, so
+* adding a priority level or a sentiment would mean a table rebuild rather than a one-line edit to
+* the enum. Every value here reaches SQLite through `Schema.encode`, so the schema already refuses
+* what a CHECK would have. The three bounds that were doing real work — both `confidence` ranges and
+* the attachment `size` floor — moved into the schemas, which is where they belonged.
+*
+* A CHECK still earns its place for an invariant Zod genuinely cannot express: `@pithy-sh/ledger`
+* constrains `held <= balance` across columns, which no per-field schema can state.
+*/
+const support_0001_threads = {
+	up: async (db) => {
+		await db.schema.createTable("pithySupportThreads").addColumn("id", "text", (c) => c.primaryKey()).addColumn("channel", "text", (c) => c.notNull().defaultTo("email")).addColumn("inboxAddress", "text").addColumn("subject", "text", (c) => c.notNull()).addColumn("fromAddress", "text", (c) => c.notNull()).addColumn("fromName", "text").addColumn("senderAuthenticated", "integer", (c) => c.notNull().defaultTo(0)).addColumn("userId", "text").addColumn("accountLinkSource", "text").addColumn("declaredCategory", "text").addColumn("category", "text", (c) => c.notNull().defaultTo("uncategorized")).addColumn("priority", "text", (c) => c.notNull().defaultTo("normal")).addColumn("sentiment", "text", (c) => c.notNull().defaultTo("neutral")).addColumn("confidence", "real").addColumn("model", "text").addColumn("classifiedAt", "integer").addColumn("archived", "integer", (c) => c.notNull().defaultTo(0)).addColumn("archivedAt", "integer").addColumn("archivedBy", "text").addColumn("messageCount", "integer", (c) => c.notNull().defaultTo(0)).addColumn("firstMessageAt", "integer", (c) => c.notNull()).addColumn("lastMessageAt", "integer", (c) => c.notNull()).addColumn("createdAt", "integer", (c) => c.notNull()).addColumn("updatedAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createIndex("pithySupportThreadsArchivedIdx").on("pithySupportThreads").columns([
+			"archived",
+			"lastMessageAt",
+			"id"
+		]).execute();
+		await db.schema.createIndex("pithySupportThreadsCategoryIdx").on("pithySupportThreads").columns([
+			"category",
+			"lastMessageAt",
+			"id"
+		]).execute();
+		await db.schema.createIndex("pithySupportThreadsDeclaredCategoryIdx").on("pithySupportThreads").columns([
+			"declaredCategory",
+			"lastMessageAt",
+			"id"
+		]).execute();
+		await db.schema.createIndex("pithySupportThreadsFromIdx").on("pithySupportThreads").columns(["fromAddress", "lastMessageAt"]).execute();
+		await db.schema.createIndex("pithySupportThreadsUserIdx").on("pithySupportThreads").column("userId").execute();
+		await db.schema.createIndex("pithySupportThreadsChannelIdx").on("pithySupportThreads").columns([
+			"channel",
+			"lastMessageAt",
+			"id"
+		]).execute();
+		await db.schema.createIndex("pithySupportThreadsUserChannelIdx").on("pithySupportThreads").columns([
+			"userId",
+			"channel",
+			"lastMessageAt",
+			"id"
+		]).execute();
+		await db.schema.createTable("pithySupportMessages").addColumn("id", "text", (c) => c.primaryKey()).addColumn("threadId", "text", (c) => c.notNull()).addColumn("direction", "text", (c) => c.notNull()).addColumn("channel", "text", (c) => c.notNull().defaultTo("email")).addColumn("submittedByUserId", "text").addColumn("context", "text").addColumn("mimeMessageId", "text").addColumn("mimeInReplyTo", "text").addColumn("mimeReferences", "text").addColumn("fromAddress", "text").addColumn("fromName", "text").addColumn("toAddress", "text").addColumn("subject", "text", (c) => c.notNull()).addColumn("textBody", "text", (c) => c.notNull()).addColumn("htmlBody", "text").addColumn("emailJobId", "text").addColumn("rawKey", "text").addColumn("rawBytes", "integer").addColumn("receivedAt", "integer", (c) => c.notNull()).addColumn("createdAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createIndex("pithySupportMessagesMimeIdIdx").on("pithySupportMessages").columns(["mimeMessageId", "toAddress"]).unique().execute();
+		await db.schema.createIndex("pithySupportMessagesThreadIdx").on("pithySupportMessages").columns(["threadId", "receivedAt"]).execute();
+		await db.schema.createIndex("pithySupportMessagesInReplyToIdx").on("pithySupportMessages").column("mimeInReplyTo").execute();
+		await db.schema.createIndex("pithySupportMessagesFromIdx").on("pithySupportMessages").columns(["fromAddress", "receivedAt"]).execute();
+		await db.schema.createIndex("pithySupportMessagesSubmitterIdx").on("pithySupportMessages").columns(["submittedByUserId", "receivedAt"]).execute();
+		await db.schema.createIndex("pithySupportMessagesChannelIdx").on("pithySupportMessages").columns([
+			"channel",
+			"direction",
+			"receivedAt"
+		]).execute();
+		await db.schema.createTable("pithySupportAttachments").addColumn("id", "text", (c) => c.primaryKey()).addColumn("messageId", "text", (c) => c.notNull()).addColumn("threadId", "text", (c) => c.notNull()).addColumn("filename", "text", (c) => c.notNull()).addColumn("contentType", "text", (c) => c.notNull()).addColumn("size", "integer", (c) => c.notNull()).addColumn("sha256", "text", (c) => c.notNull()).addColumn("storageKey", "text", (c) => c.notNull()).addColumn("contentId", "text").addColumn("inline", "integer", (c) => c.notNull().defaultTo(0)).addColumn("createdAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createIndex("pithySupportAttachmentsMessageIdx").on("pithySupportAttachments").column("messageId").execute();
+		await db.schema.createIndex("pithySupportAttachmentsThreadIdx").on("pithySupportAttachments").column("threadId").execute();
+		await db.schema.createTable("pithySupportClassifications").addColumn("id", "text", (c) => c.primaryKey()).addColumn("threadId", "text", (c) => c.notNull()).addColumn("messageId", "text", (c) => c.notNull()).addColumn("category", "text", (c) => c.notNull()).addColumn("priority", "text", (c) => c.notNull()).addColumn("sentiment", "text", (c) => c.notNull()).addColumn("confidence", "real", (c) => c.notNull()).addColumn("model", "text", (c) => c.notNull()).addColumn("createdAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createIndex("pithySupportClassificationsThreadIdx").on("pithySupportClassifications").columns(["threadId", "createdAt"]).execute();
+		await db.schema.createIndex("pithySupportClassificationsModelIdx").on("pithySupportClassifications").columns(["model", "createdAt"]).execute();
+		await db.schema.createTable("pithySupportThreadFlags").addColumn("id", "text", (c) => c.primaryKey()).addColumn("threadId", "text", (c) => c.notNull()).addColumn("viewer", "text", (c) => c.notNull()).addColumn("read", "integer", (c) => c.notNull().defaultTo(0)).addColumn("snoozedUntil", "integer").addColumn("createdAt", "integer", (c) => c.notNull()).addColumn("updatedAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createIndex("pithySupportThreadFlagsViewerIdx").on("pithySupportThreadFlags").columns(["threadId", "viewer"]).unique().execute();
+	},
+	down: async (db) => {
+		await db.schema.dropIndex("pithySupportThreadFlagsViewerIdx").execute();
+		await db.schema.dropTable("pithySupportThreadFlags").execute();
+		await db.schema.dropIndex("pithySupportClassificationsModelIdx").execute();
+		await db.schema.dropIndex("pithySupportClassificationsThreadIdx").execute();
+		await db.schema.dropTable("pithySupportClassifications").execute();
+		await db.schema.dropIndex("pithySupportAttachmentsThreadIdx").execute();
+		await db.schema.dropIndex("pithySupportAttachmentsMessageIdx").execute();
+		await db.schema.dropTable("pithySupportAttachments").execute();
+		await db.schema.dropIndex("pithySupportMessagesChannelIdx").execute();
+		await db.schema.dropIndex("pithySupportMessagesSubmitterIdx").execute();
+		await db.schema.dropIndex("pithySupportMessagesFromIdx").execute();
+		await db.schema.dropIndex("pithySupportMessagesInReplyToIdx").execute();
+		await db.schema.dropIndex("pithySupportMessagesThreadIdx").execute();
+		await db.schema.dropIndex("pithySupportMessagesMimeIdIdx").execute();
+		await db.schema.dropTable("pithySupportMessages").execute();
+		await db.schema.dropIndex("pithySupportThreadsUserChannelIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsChannelIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsUserIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsFromIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsDeclaredCategoryIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsCategoryIdx").execute();
+		await db.schema.dropIndex("pithySupportThreadsArchivedIdx").execute();
+		await db.schema.dropTable("pithySupportThreads").execute();
+	}
+};
+//#endregion
+export { support_0001_threads };

package/dist/mime/address.d.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * What a MIME header contributes that an address rule does not.
+ *
+ * Addresses themselves are `@pithy-sh/core/src/address/address` — `parseAddress` reads one out of a
+ * header and `normalizeAddress` puts it in the form every comparison in the kit is against. This
+ * capability used to own that rule; it does not any more, because `auth`, `email` and `testers`
+ * compare addresses too, and four rules is four chances to disagree about whether two strings are the
+ * same person. That disagreement presents as one customer with two threads, not as anything about
+ * addresses.
+ *
+ * What is left here is the display name, which is this capability alone: nobody else stores one, and it
+ * is the half of a `From` header that is free text an attacker wrote.
+ */
+/**
+ * A display name, made safe to store.
+ *
+ * Trimmed, bounded, and stripped of control characters — including the bidirectional overrides that
+ * let `moc.elpmaxe@ada` render as something else entirely. The result is still untrusted text that a
+ * renderer must escape; this only guarantees it is text.
+ */
+export declare function normalizeDisplayName(value: string | null | undefined): string | undefined;
+//# sourceMappingURL=address.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/mime/address.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYzF"}

package/dist/mime/address.js

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/mime/address.ts
+/**
+* What a MIME header contributes that an address rule does not.
+*
+* Addresses themselves are `@pithy-sh/core/src/address/address` — `parseAddress` reads one out of a
+* header and `normalizeAddress` puts it in the form every comparison in the kit is against. This
+* capability used to own that rule; it does not any more, because `auth`, `email` and `testers`
+* compare addresses too, and four rules is four chances to disagree about whether two strings are the
+* same person. That disagreement presents as one customer with two threads, not as anything about
+* addresses.
+*
+* What is left here is the display name, which is this capability alone: nobody else stores one, and it
+* is the half of a `From` header that is free text an attacker wrote.
+*/
+/**
+* A display name, made safe to store.
+*
+* Trimmed, bounded, and stripped of control characters — including the bidirectional overrides that
+* let `moc.elpmaxe@ada` render as something else entirely. The result is still untrusted text that a
+* renderer must escape; this only guarantees it is text.
+*/
+function normalizeDisplayName(value) {
+	if (typeof value !== "string") return void 0;
+	const cleaned = value.replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, "").trim().slice(0, 200);
+	return cleaned.length > 0 ? cleaned : void 0;
+}
+//#endregion
+export { normalizeDisplayName };

package/dist/mime/parse.d.ts

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * Inbound MIME, parsed into the shape the rest of the capability works in.
+ *
+ * `@pithy-sh/email` already depends on `postal-mime` and already parses inbound mail — but only its
+ * headers, to classify a bounce. Everything below the headers is untouched there, so multipart
+ * bodies, attachments, and the threading chain are parsed here for the first time.
+ *
+ * **This module does not sanitize.** `html` comes back exactly as it arrived, and the caller runs it
+ * through `sanitizeHtml` before anything stores or renders it. Keeping the two apart is what lets
+ * this file be unit-tested under node against real messages — `HTMLRewriter` is a Workers global —
+ * and it keeps the parse honest: a sanitizer that ran here would quietly make the raw bytes and the
+ * parsed form disagree about what arrived.
+ */
+/** One attachment, decoded, with its declared metadata carried as-declared. */
+export interface ParsedAttachment {
+    /** The filename the sender declared, already stripped of path separators and control characters. */
+    filename: string;
+    /** The MIME type the sender declared. Recorded, never honored by a serve path. */
+    contentType: string;
+    /** The decoded bytes. */
+    bytes: Uint8Array;
+    /** The `Content-ID`, when the part carried one — what an inline image refers to by `cid:`. */
+    contentId?: string;
+    /** Whether the part declared `Content-Disposition: inline`. */
+    inline: boolean;
+}
+/** One inbound message, parsed. */
+export interface ParsedInboundMessage {
+    /** The `Message-ID`, without angle brackets. Absent when the sender omitted one. */
+    messageId?: string;
+    /** The `In-Reply-To` id, without angle brackets — the direct parent. */
+    inReplyTo?: string;
+    /** The `References` chain, oldest first. */
+    references: string[];
+    /** The sender's address, normalized. */
+    fromAddress: string;
+    /** The sender's display name, if any — untrusted text, already stripped of control characters. */
+    fromName?: string;
+    /** Every address named in `To`/`Cc`/`Delivered-To`, normalized. Corroborating evidence, never authority. */
+    headerRecipients: string[];
+    /** The subject, bounded. Empty when the message had none. */
+    subject: string;
+    /** The plain-text body. Empty when the message carried only HTML — the caller derives text from it. */
+    text: string;
+    /** The HTML body **exactly as it arrived**, unsanitised. Absent when the message carried none. */
+    html?: string;
+    /** The decoded attachments, in the order the parts appeared. */
+    attachments: ParsedAttachment[];
+    /**
+     * The `Authentication-Results` verdicts the receiving MTA stamped, lowercased, keyed by method
+     * (`dmarc`, `spf`, `dkim`). Empty when the header was absent — which is itself a signal.
+     *
+     * Read from the **topmost** such header only. A sender may include one of their own, and it will be
+     * below the MTA's; reading any but the first is a forged verdict.
+     */
+    authResults: Record<string, string>;
+    /**
+     * Which sender-authentication headers were actually present in the received bytes.
+     *
+     * **A diagnostic, not a signal** — nothing branches on it, and it is deliberately not stored. It
+     * exists to settle a question this package cannot answer by reading documentation: whether
+     * Cloudflare Email Routing delivers a Worker the headers a sender-authenticity check would need.
+     * `Authentication-Results`, `Received`, and `DKIM-Signature` are all reported missing from
+     * `message.headers` (cloudflare/workerd#6740), but `message.raw` — which is what this parses — is
+     * documented as the raw MIME and is a different surface. Inferring the answer from a GitHub issue
+     * is guessing; logging what arrived means the first real delivery answers it.
+     *
+     * See issue #47, which is where that live verification lives.
+     */
+    authHeadersSeen: string[];
+    /**
+     * Whether this looks machine-generated: an out-of-office, a mailing-list post, or a bulk send.
+     *
+     * Not a reason to drop the message — a vacation responder appended to a real thread is context an
+     * operator wants — but a good reason not to pay a model to classify it. Read by the ingest path to
+     * skip the classification dispatch, which is the only cost per message that is not fixed.
+     */
+    autoSubmitted: boolean;
+}
+/** The longest text body stored, **in bytes**. A support request needing more than this has a file attached. */
+export declare const MAX_TEXT_BODY: number;
+/**
+ * Make a declared filename safe to store and display.
+ *
+ * Path separators go first — a name is never part of a storage key here, but a dashboard that offers
+ * a download should not be handed `../../etc/passwd` to put in a `Content-Disposition`. Control
+ * characters and bidirectional overrides go with them: a filename carrying a right-to-left override
+ * renders as something other than what it is, which is the oldest attachment trick there is.
+ */
+export declare function safeFilename(value: string | null | undefined): string;
+export declare function parseAuthResults(value: string | undefined, expectedAuthservId?: string): Record<string, string>;
+/** Parse a raw MIME message. Throws `support/unparseable_message` when there is no usable sender. */
+export declare function parseInbound(raw: string | ArrayBuffer | Uint8Array, options?: {
+    expectedAuthservId?: string;
+}): Promise<ParsedInboundMessage>;
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/mime/parse.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4GAA4G;IAC5G,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;;;;;;;;OAYG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAiBD,gHAAgH;AAChH,eAAO,MAAM,aAAa,QAAa,CAAC;AAkBxC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAWrE;AAuBD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8C/G;AAmBD,qGAAqG;AACrG,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,EACtC,OAAO,GAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,OAAO,CAAC,oBAAoB,CAAC,CA6D/B"}

package/dist/mime/parse.js

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportUnparseableMessageError } from "../error/errors.js";
+import { normalizeMessageId, parseReferences } from "./threading.js";
+import { normalizeDisplayName } from "./address.js";
+import { truncateToBytes } from "./truncate.js";
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+import PostalMime from "postal-mime";
+//#region src/mime/parse.ts
+/**
+* A verdict at the start of its clause. Anchored: an unanchored scan matched `method=result` inside a
+* *property tag*, and `smtp.mailfrom=` carries an address the sender chose.
+*/
+const VERDICT = /^\s*(dmarc|spf|dkim|iprev)\s*=\s*([a-z]+)/i;
+/**
+* The headers whose presence decides whether in-Worker sender authentication is possible at all.
+* Reported, never trusted — see {@link ParsedInboundMessage.authHeadersSeen}.
+*/
+const AUTH_HEADERS = [
+	"authentication-results",
+	"dkim-signature",
+	"arc-authentication-results",
+	"received"
+];
+/** The longest subject stored. Long enough for any real one; short enough not to be a storage lever. */
+const MAX_SUBJECT = 500;
+/** The longest text body stored, **in bytes**. A support request needing more than this has a file attached. */
+const MAX_TEXT_BODY = 262144;
+/** Pull the first usable address out of whatever `postal-mime` produced for a header. */
+function addressesOf(value) {
+	const list = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+	const found = [];
+	for (const entry of list) {
+		const members = entry.group !== void 0 ? entry.group : entry.address !== void 0 ? [entry] : [];
+		for (const member of members) {
+			const normalized = parseAddress(member.address);
+			if (normalized) found.push(normalized);
+		}
+	}
+	return found;
+}
+/**
+* Make a declared filename safe to store and display.
+*
+* Path separators go first — a name is never part of a storage key here, but a dashboard that offers
+* a download should not be handed `../../etc/passwd` to put in a `Content-Disposition`. Control
+* characters and bidirectional overrides go with them: a filename carrying a right-to-left override
+* renders as something other than what it is, which is the oldest attachment trick there is.
+*/
+function safeFilename(value) {
+	const cleaned = (value ?? "").replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, "").replace(/[/\\]/g, "_").trim().slice(0, 200);
+	return cleaned.length > 0 ? cleaned : "attachment";
+}
+/**
+* Parse `Authentication-Results` into `method → verdict`.
+*
+* Cloudflare stamps this before a message reaches a Worker, so it is the one trustworthy statement
+* about the sender available here — everything else in the message is the sender's own claim. The
+* format is `mta.example.com; spf=pass smtp.mailfrom=a@b; dkim=pass header.d=b; dmarc=pass`, and
+* only the method/verdict pairs are read; the property tags after each are informational.
+*/
+/**
+* The authserv-id out of an `Authentication-Results` first clause: the host name, with the optional
+* version token and any CFWS comments removed, lowercased.
+*/
+function authservIdOf(clause) {
+	return (clause ?? "").replace(/\([^)]*\)/g, " ").trim().replace(/\s+\d+$/, "").trim().toLowerCase();
+}
+function parseAuthResults(value, expectedAuthservId) {
+	if (typeof value !== "string") return {};
+	const clauses = value.replace(/"(?:[^"\\]|\\.)*"/g, "\"\"").split(";");
+	const leadingIsVerdict = VERDICT.test(clauses[0] ?? "");
+	if (expectedAuthservId !== void 0 && !leadingIsVerdict) {
+		if (authservIdOf(clauses[0]) !== authservIdOf(expectedAuthservId)) return {};
+	}
+	const results = {};
+	for (const clause of leadingIsVerdict ? clauses : clauses.slice(1)) {
+		const match = VERDICT.exec(clause);
+		const method = match?.[1]?.toLowerCase();
+		const verdict = match?.[2]?.toLowerCase();
+		if (method && verdict && !(method in results)) results[method] = verdict;
+	}
+	return results;
+}
+/** Whether a header set marks the message as machine-generated. */
+function isAutoSubmitted(headers) {
+	if ((headers.get("auto-submitted")?.toLowerCase() ?? "").startsWith("auto-")) return true;
+	const precedence = headers.get("precedence")?.toLowerCase() ?? "";
+	if ([
+		"bulk",
+		"list",
+		"junk",
+		"auto_reply"
+	].includes(precedence)) return true;
+	return headers.has("list-id") || headers.has("list-unsubscribe") || headers.has("x-autoreply");
+}
+/** Decode `postal-mime`'s attachment content into bytes, whatever form it handed back. */
+function attachmentBytes(attachment) {
+	const content = attachment.content;
+	if (typeof content === "string") return new TextEncoder().encode(content);
+	if (content instanceof Uint8Array) return content;
+	return new Uint8Array(content);
+}
+/** Parse a raw MIME message. Throws `support/unparseable_message` when there is no usable sender. */
+async function parseInbound(raw, options = {}) {
+	let email;
+	try {
+		email = await PostalMime.parse(raw);
+	} catch (cause) {
+		throw new SupportUnparseableMessageError({ detail: "postal-mime could not parse the message" }, { cause });
+	}
+	const headers = /* @__PURE__ */ new Map();
+	for (const header of email.headers) {
+		const key = header.key.toLowerCase();
+		if (!headers.has(key)) headers.set(key, header.value);
+	}
+	const fromAddress = addressesOf(email.from)[0];
+	if (!fromAddress) throw new SupportUnparseableMessageError({ detail: "the message carried no parseable From address" });
+	const from = Array.isArray(email.from) ? email.from[0] : email.from;
+	const inReplyTo = normalizeMessageId(email.inReplyTo);
+	return {
+		messageId: normalizeMessageId(email.messageId),
+		inReplyTo,
+		references: parseReferences(email.references),
+		fromAddress,
+		fromName: normalizeDisplayName(from?.name),
+		headerRecipients: [.../* @__PURE__ */ new Set([
+			...addressesOf(email.to),
+			...addressesOf(email.cc),
+			...parseAddress(email.deliveredTo) ? [parseAddress(email.deliveredTo)] : []
+		])],
+		subject: (email.subject ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_SUBJECT),
+		text: truncateToBytes(email.text ?? "", MAX_TEXT_BODY),
+		html: email.html,
+		attachments: email.attachments.map((attachment) => ({
+			filename: safeFilename(attachment.filename),
+			contentType: attachment.mimeType || "application/octet-stream",
+			bytes: attachmentBytes(attachment),
+			contentId: attachment.contentId?.replace(/^<|>$/g, "") || void 0,
+			inline: attachment.disposition === "inline"
+		})),
+		authResults: parseAuthResults(headers.get("authentication-results"), options.expectedAuthservId),
+		authHeadersSeen: AUTH_HEADERS.filter((name) => headers.has(name)),
+		autoSubmitted: isAutoSubmitted(headers)
+	};
+}
+//#endregion
+export { MAX_TEXT_BODY, parseAuthResults, parseInbound, safeFilename };