@pithy-sh/support 0.1.2 → 0.1.3

package/dist/http/schemas.js

@@ -0,0 +1,89 @@
+import { MAX_SUBMISSION_BODY_CHARS } from "../config/config.js";
+import { SupportChannel, SupportPriority, SupportSentiment } from "../data/enums.js";
+import { SupportSubmissionContext } from "../data/message.js";
+import "../store/paging.js";
+import { z } from "zod";
+//#region src/http/schemas.ts
+/**
+* The request contracts every support route declares (CLAUDE.md §HTTP).
+*
+* Every one of these is a **bound on something a caller chose**, which is the whole job: a control-
+* plane credential is verified, but verified is not the same as trusted, and a management client with
+* a bug can ask for a million rows as easily as a hostile one can.
+*
+* The category filter is a bounded string rather than an enum, and that is deliberate: the taxonomy
+* is federated, so the valid set is not known here — and building the schema from the configured set
+* would make a filter for a category an adopter just removed a 400 instead of an empty list, which is
+* a worse answer to the same question. The value is only ever compared, never interpreted.
+*/
+/** A thread id in the path. */
+const ThreadIdParam = z.object({ id: z.string().uuid().describe("The thread's UUID. A param schema constrains the string; the handler still does the lookup.") }).describe("The path parameters of every single-thread route.");
+/** A category key as a filter — bounded and shaped, never resolved against the configured set. */
+const CategoryFilter = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_]*$/).describe("One category key from this project's effective taxonomy. A key an adopter removed simply matches nothing.");
+/** The inbox listing query. */
+const ListThreadsQuery = z.object({
+	archived: z.enum(["true", "false"]).optional().describe("`true` for the done pile, `false` or absent for the open inbox — which is the default on purpose."),
+	category: CategoryFilter.optional().describe("Filter to one category — what the classifier made of it."),
+	declaredCategory: CategoryFilter.optional().describe("Filter to one category **the submitter chose**, which is a different question from `category` and answers it about different threads. Combining the two is how an operator finds the disagreements; asking for this one alone is how they triage a project with `ai.enabled: false`, where nothing ever writes the other."),
+	priority: SupportPriority.optional().describe("Filter to one priority."),
+	sentiment: SupportSentiment.optional().describe("Filter to one sentiment."),
+	channel: SupportChannel.optional().describe("Filter to one channel — `email` for mail, `app` for what signed-in users filed from inside the app. Absent shows both, which is the right default for an inbox that is one queue however things arrived."),
+	inbox: z.string().min(3).max(256).optional().describe("Filter to one configured inbox address, for a Worker serving several."),
+	q: z.string().min(1).max(200).optional().describe("Free text over subjects and bodies. Keyword search — the words people actually remember."),
+	cursor: z.string().max(512).optional().describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page."),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("How many threads to return. Bounded, because a verified client can still have a bug.")
+}).describe("The inbox query: what to filter by, what to search for, and where to resume.");
+/** The archive/unarchive body. */
+const ArchiveThreadInput = z.object({ archived: z.boolean().describe("`true` marks the conversation done; `false` reopens it. Explicit rather than a toggle, so a retried request lands on the state the caller meant rather than flipping it back.") }).describe("Mark a conversation done, or reopen it.");
+/** The reply body. */
+const ReplyInput = z.object({
+	body: z.string().min(1).max(5e4).describe("The reply text, as a human wrote and edited it. Rendered HTML-escaped into the adopter's email shell — it is prose, never markup."),
+	agentName: z.string().min(1).max(80).optional().describe("Who is answering, signed at the bottom. Omitted rather than guessed.")
+}).describe("An answer to send to the customer.");
+/** The per-viewer flags body. */
+const FlagsInput = z.object({
+	read: z.boolean().optional().describe("Mark read or unread. Absent leaves it alone."),
+	snoozedUntil: z.string().datetime().nullish().describe("Hide this thread from your inbox until this ISO-8601 moment. `null` clears a snooze; absent leaves it alone. A time rather than a flag, so it expires on its own and nothing has to sweep.")
+}).describe("One viewer's private read and snooze state.");
+/**
+* One file on an in-app submission.
+*
+* The bytes arrive base64-encoded in JSON so the whole request stays one Zod object on the route line,
+* like every other route in this capability. **The size and type bounds are not here**: they are the
+* adopter's `submission.attachments` config, resolved in the handler, because a request schema is built
+* once at module load and cannot know them. What this bounds is the shape — a filename that renders, a
+* MIME type that looks like one, and a payload that is base64 at all.
+*/
+const SubmittedAttachmentInput = z.object({
+	filename: z.string().min(1).max(255).describe("The filename as the client declares it. **Recorded and never honored** — the R2 key is server-derived, so this is metadata a console renders escaped, not a path anything resolves."),
+	contentType: z.string().min(3).max(128).regex(/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/).describe("The MIME type as the client declares it, lowercased, checked against the configured allowlist in the handler. Never used to serve the bytes: every object is stored as `application/octet-stream`, because R2 echoes a stored type back on a presigned GET and a browser renders `text/html`."),
+	data: z.union([z.base64(), z.base64url()]).describe("The file's bytes, base64 — the standard alphabet or the URL-safe one, because a client whose encoder emits the latter has not made a mistake worth a 400. The configured `maxBytes` bound is measured on the **decoded** length, which is a third smaller than this string.")
+}).describe("One file attached to an in-app support request, as bytes a signed-in client encoded.");
+/**
+* The in-app submission body.
+*
+* **Nothing here names an account, and nothing here could.** The submitter is `c.var.auth.userId`,
+* proved before this schema ran — a `userId` field would be a client-supplied identity on the one
+* surface whose whole argument is that it does not need one.
+*
+* The lengths are the hard ceilings from `config/config.ts`, not the adopter's configured bounds: this
+* schema is built once at module load, and the configured numbers are applied in the handler where the
+* resolved config lives. A body over the ceiling never reaches a handler at all.
+*/
+const SubmitFeedbackInput = z.object({
+	subject: z.string().min(1).max(500).describe("What the request is about. Becomes the thread's name in the inbox and the subject of every reply."),
+	body: z.string().min(1).max(MAX_SUBMISSION_BODY_CHARS).describe("The report itself, as the person wrote it. Plain text — it is prose, never markup."),
+	declaredCategory: CategoryFilter.optional().describe("What the person writing says this is about, from your app's own chooser. **Named for what it is, on the wire as well as in the row**: a field called `category` here would land in a column of that name that this never touches, which is the exact confusion the two columns exist to prevent. Bounded to a key's shape here and checked against your effective taxonomy in the handler — a key you do not declare is **refused**, because a chooser was built from that taxonomy and a value outside it is the client's bug. Accepted only when opening a request: sent alongside `threadId` it is refused rather than ignored."),
+	threadId: z.string().uuid().optional().describe("Continue this conversation instead of opening one. Accepted only for the caller's **own** app thread; anybody else's answers 404, which is the same answer a thread that does not exist gets — a 403 would confirm the id names a real conversation."),
+	context: SupportSubmissionContext.optional().describe("What the app knows and the user did not type — screen, build, platform, environment, locale. A closed set: an undeclared key is refused rather than stored, so this cannot quietly become a telemetry pipe."),
+	attachments: z.array(SubmittedAttachmentInput).max(10).default([]).describe("Files attached to the request. Bounded by `submission.attachments` in the adopter's config — count, decoded size, and an allowlist of types — and refused as a whole rather than silently trimmed. The ceiling here is the one that holds whatever that config says, and it is checked before any payload is decoded.")
+}).describe("An in-app support request from a signed-in user: what it is about, what happened, and what it carries.");
+/** The submitter's own thread list. */
+const MyThreadsQuery = z.object({
+	cursor: z.string().max(512).optional().describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page."),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("How many conversations to return. Bounded, because a signed-in caller can still have a bug.")
+}).describe("The submitter's own conversation list. No filters: this is one person's handful of requests, not an inbox to triage.");
+/** The canned-reply catalog query. */
+const RepliesQuery = z.object({ category: CategoryFilter.optional().describe("Order the catalog for this category — its snippets first, then the general-purpose ones. Ordering, never filtering: a misclassified thread must not hide the snippet its operator actually needs.") }).describe("How to order the canned reply catalog.");
+//#endregion
+export { ArchiveThreadInput, FlagsInput, ListThreadsQuery, MyThreadsQuery, RepliesQuery, ReplyInput, SubmitFeedbackInput, SubmittedAttachmentInput, ThreadIdParam };

package/dist/http/scopes.d.ts

@@ -0,0 +1,56 @@
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+/**
+ * Support's control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+ * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
+ * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
+ * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
+ * one compiled `PithyHonoEnv`, which reached core's `capability.ts`, which named Worker globals that
+ * program has none of. **This module imports types and nothing else, and a gate holds it there**:
+ * `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
+ *
+ * ## Five scopes, because these are five different blast radii
+ *
+ * The temptation is one `support:admin` flag. It is wrong on the merits, the same way payments'
+ * single flag was: **reading** an inbox exposes every customer's private correspondence, while
+ * **replying** sends mail to a real person under the adopter's domain and DKIM. Those are not the
+ * same permission, and a tool that needed one should never silently hold the other. `scopeCovers`
+ * matches exactly, with no prefix or wildcard rule, so holding one confers nothing about the rest.
+ *
+ * The split that matters most is `reply`. A compromised read credential is a privacy incident; a
+ * compromised reply credential is somebody sending mail *as the adopter* to their own customers,
+ * which is a phishing platform with a verified sending domain attached.
+ */
+/** Read the inbox: list threads, read one, and see the sender's linked account and purchases. */
+export declare const SUPPORT_THREADS_READ_SCOPE: ControlPlaneScope;
+/** Mark a thread done or reopen it — the one shared piece of state in the model. */
+export declare const SUPPORT_THREADS_ARCHIVE_SCOPE: ControlPlaneScope;
+/**
+ * Send mail to a customer under the adopter's domain. The most dangerous of the five and the reason
+ * a single admin flag was never an option.
+ */
+export declare const SUPPORT_THREADS_REPLY_SCOPE: ControlPlaneScope;
+/** Re-run the model over a thread, overwriting its current classification. */
+export declare const SUPPORT_THREADS_RECLASSIFY_SCOPE: ControlPlaneScope;
+/** Set a viewer's own read/snooze flags. Private, uncoordinated, and the least dangerous thing here. */
+export declare const SUPPORT_THREADS_FLAG_SCOPE: ControlPlaneScope;
+/**
+ * Every control-plane scope support defines — what `pithy dashboard connect` offers for this
+ * capability, and the list a manifest or a doc quotes rather than re-typing.
+ */
+export declare const SUPPORT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
+/**
+ * Support's management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scopes so the scope a route demands and the scope a manifest advertises are
+ * the same constant. `basePath` is a parameter and never a default: an adopter who mounted support
+ * at `/inbox` must get a manifest naming `/inbox/threads`, or a client composing its calls from the
+ * manifest would 404 against exactly the adopters who customized anything.
+ *
+ * The summaries say what the operation is *for*. A client renders these next to a button somebody is
+ * about to press on a real customer's conversation.
+ */
+export declare function supportAdminRoutes(basePath: string): AdminRoute[];
+//# sourceMappingURL=scopes.d.ts.map

package/dist/http/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/http/scopes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iGAAiG;AACjG,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAA2C,CAAC;AAEtF,8EAA8E;AAC9E,eAAO,MAAM,gCAAgC,EAAE,iBAAgD,CAAC;AAEhG,wGAAwG;AACxG,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,iBAAiB,EAMpE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CA6CjE"}

package/dist/http/scopes.js

@@ -0,0 +1,107 @@
+//#region src/http/scopes.ts
+/**
+* Support's control-plane scopes, and the admin surface a manifest advertises.
+*
+* **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+* client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
+* writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
+* program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
+* one compiled `PithyHonoEnv`, which reached core's `capability.ts`, which named Worker globals that
+* program has none of. **This module imports types and nothing else, and a gate holds it there**:
+* `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
+*
+* ## Five scopes, because these are five different blast radii
+*
+* The temptation is one `support:admin` flag. It is wrong on the merits, the same way payments'
+* single flag was: **reading** an inbox exposes every customer's private correspondence, while
+* **replying** sends mail to a real person under the adopter's domain and DKIM. Those are not the
+* same permission, and a tool that needed one should never silently hold the other. `scopeCovers`
+* matches exactly, with no prefix or wildcard rule, so holding one confers nothing about the rest.
+*
+* The split that matters most is `reply`. A compromised read credential is a privacy incident; a
+* compromised reply credential is somebody sending mail *as the adopter* to their own customers,
+* which is a phishing platform with a verified sending domain attached.
+*/
+/** Read the inbox: list threads, read one, and see the sender's linked account and purchases. */
+const SUPPORT_THREADS_READ_SCOPE = "support:threads:read";
+/** Mark a thread done or reopen it — the one shared piece of state in the model. */
+const SUPPORT_THREADS_ARCHIVE_SCOPE = "support:threads:archive";
+/**
+* Send mail to a customer under the adopter's domain. The most dangerous of the five and the reason
+* a single admin flag was never an option.
+*/
+const SUPPORT_THREADS_REPLY_SCOPE = "support:threads:reply";
+/** Re-run the model over a thread, overwriting its current classification. */
+const SUPPORT_THREADS_RECLASSIFY_SCOPE = "support:threads:reclassify";
+/** Set a viewer's own read/snooze flags. Private, uncoordinated, and the least dangerous thing here. */
+const SUPPORT_THREADS_FLAG_SCOPE = "support:threads:flag";
+/**
+* Every control-plane scope support defines — what `pithy dashboard connect` offers for this
+* capability, and the list a manifest or a doc quotes rather than re-typing.
+*/
+const SUPPORT_CONTROL_PLANE_SCOPES = [
+	SUPPORT_THREADS_READ_SCOPE,
+	SUPPORT_THREADS_ARCHIVE_SCOPE,
+	SUPPORT_THREADS_REPLY_SCOPE,
+	SUPPORT_THREADS_RECLASSIFY_SCOPE,
+	SUPPORT_THREADS_FLAG_SCOPE
+];
+/**
+* Support's management surface, as `GET /control-plane/manifest` reports it.
+*
+* Declared beside the scopes so the scope a route demands and the scope a manifest advertises are
+* the same constant. `basePath` is a parameter and never a default: an adopter who mounted support
+* at `/inbox` must get a manifest naming `/inbox/threads`, or a client composing its calls from the
+* manifest would 404 against exactly the adopters who customized anything.
+*
+* The summaries say what the operation is *for*. A client renders these next to a button somebody is
+* about to press on a real customer's conversation.
+*/
+function supportAdminRoutes(basePath) {
+	return [
+		{
+			method: "GET",
+			path: `${basePath}/threads`,
+			scope: SUPPORT_THREADS_READ_SCOPE,
+			summary: "List the inbox, newest first, filtered by category, priority, and archived, searched by text."
+		},
+		{
+			method: "GET",
+			path: `${basePath}/threads/:id`,
+			scope: SUPPORT_THREADS_READ_SCOPE,
+			summary: "Read one conversation, with the sender's linked account and what they bought."
+		},
+		{
+			method: "POST",
+			path: `${basePath}/threads/:id/archive`,
+			scope: SUPPORT_THREADS_ARCHIVE_SCOPE,
+			summary: "Mark a conversation done, or reopen one."
+		},
+		{
+			method: "POST",
+			path: `${basePath}/threads/:id/reply`,
+			scope: SUPPORT_THREADS_REPLY_SCOPE,
+			summary: "Answer the customer, threaded so their mail client keeps one conversation."
+		},
+		{
+			method: "POST",
+			path: `${basePath}/threads/:id/reclassify`,
+			scope: SUPPORT_THREADS_RECLASSIFY_SCOPE,
+			summary: "Re-run the classifier over this conversation's latest inbound message."
+		},
+		{
+			method: "POST",
+			path: `${basePath}/threads/:id/flags`,
+			scope: SUPPORT_THREADS_FLAG_SCOPE,
+			summary: "Set your own read and snooze state for a conversation. Private to you."
+		},
+		{
+			method: "GET",
+			path: `${basePath}/replies`,
+			scope: SUPPORT_THREADS_READ_SCOPE,
+			summary: "The canned reply catalog — starting points to pick from, ordered for a thread's category."
+		}
+	];
+}
+//#endregion
+export { SUPPORT_CONTROL_PLANE_SCOPES, SUPPORT_THREADS_ARCHIVE_SCOPE, SUPPORT_THREADS_FLAG_SCOPE, SUPPORT_THREADS_READ_SCOPE, SUPPORT_THREADS_RECLASSIFY_SCOPE, SUPPORT_THREADS_REPLY_SCOPE, supportAdminRoutes };

package/dist/http/views.d.ts

@@ -0,0 +1,36 @@
+import type { SupportMessage } from "../data/message";
+import type { SupportThread } from "../data/thread";
+import type { SenderContext } from "../link/sender";
+import type { ListedThread } from "../store/threads";
+import type { SenderContextView, SupportAttachmentView, SupportListedThreadView, SupportMessageView, SupportMyMessageView, SupportMyThreadView, SupportThreadView } from "./responses";
+/** Project one thread row. */
+export declare function threadView(thread: SupportThread): SupportThreadView;
+/** Project one thread for the inbox, carrying this viewer's own read and snooze state. */
+export declare function listedThreadView(thread: ListedThread): SupportListedThreadView;
+/**
+ * Project one message.
+ *
+ * The threading internals — `mimeMessageId`, `mimeInReplyTo`, `mimeReferences`, `rawKey`, `rawBytes` —
+ * are dropped. They are how a reply is stitched to its parent, and an operator would never act on one.
+ * `rawKey` in particular is the R2 object holding the message exactly as it arrived, which is the one
+ * copy of this data that has had nothing done to it.
+ */
+export declare function messageView(message: SupportMessage): SupportMessageView;
+/**
+ * Project one thread for the person who opened it.
+ *
+ * **Built from scratch rather than from {@link threadView}, and that is the security boundary.** A
+ * submitter's view derived by omitting fields from an operator's would disclose the next column
+ * somebody adds, silently, on the day they add it — the failure would be a default rather than a
+ * decision. Starting from nothing means a field reaches a customer only because somebody wrote it
+ * here.
+ *
+ * So: no classification, no priority, no sentiment, no confidence, no model, no viewer flags, no
+ * account link, no `archivedBy`, no addresses. What is left is their conversation.
+ */
+export declare function myThreadView(thread: SupportThread): SupportMyThreadView;
+/** Project one message for the person in the conversation. Their own attachments ride along. */
+export declare function myMessageView(message: SupportMessage, attachments: SupportAttachmentView[]): SupportMyMessageView;
+/** Project the customer context beside a conversation. */
+export declare function senderView(sender: SenderContext): SenderContextView;
+//# sourceMappingURL=views.d.ts.map

package/dist/http/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAyBrB,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CA2BnE;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,uBAAuB,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB,CAgBvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,mBAAmB,CASvE;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,qBAAqB,EAAE,GAAG,oBAAoB,CAYjH;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CA4BnE"}

package/dist/http/views.js

@@ -0,0 +1,144 @@
+//#region src/http/views.ts
+/**
+* The projections between a support row and the wire.
+*
+* Every return type is `z.output` of the matching object in `responses.ts`, so what this Worker sends
+* and what a management client validates against are one declaration. A field added to one and not
+* the other does not compile.
+*
+* **These convert dates to ISO-8601 strings, and that changes nothing on the wire.** A `Date` handed
+* to `c.json` serializes as an ISO string already — so the bytes were always this, while the type
+* claimed a `Date` no client ever received and no schema could describe. Converting explicitly is
+* what makes the response statable, and it is the whole reason the fields could be typed at all.
+*
+* **A row is never spread.** Each projection names its fields, so a column added to
+* `pithy_support_threads` is disclosed by a decision rather than by default — which is the same rule
+* every other capability's admin surface follows, and the one a `SELECT *` handed to `c.json` breaks
+* silently.
+*/
+/** An ISO string, or null. */
+function iso(date) {
+	return date ? date.toISOString() : null;
+}
+/** Project one thread row. */
+function threadView(thread) {
+	return {
+		id: thread.id,
+		channel: thread.channel,
+		inboxAddress: thread.inboxAddress ?? null,
+		subject: thread.subject,
+		fromAddress: thread.fromAddress,
+		fromName: thread.fromName ?? null,
+		senderAuthenticated: thread.senderAuthenticated,
+		userId: thread.userId ?? null,
+		accountLinkSource: thread.accountLinkSource ?? null,
+		declaredCategory: thread.declaredCategory ?? null,
+		category: thread.category,
+		priority: thread.priority,
+		sentiment: thread.sentiment,
+		confidence: thread.confidence ?? null,
+		model: thread.model ?? null,
+		classifiedAt: iso(thread.classifiedAt),
+		archived: thread.archived,
+		archivedAt: iso(thread.archivedAt),
+		archivedBy: thread.archivedBy ?? null,
+		messageCount: thread.messageCount,
+		firstMessageAt: thread.firstMessageAt.toISOString(),
+		lastMessageAt: thread.lastMessageAt.toISOString(),
+		createdAt: thread.createdAt.toISOString(),
+		updatedAt: thread.updatedAt.toISOString()
+	};
+}
+/** Project one thread for the inbox, carrying this viewer's own read and snooze state. */
+function listedThreadView(thread) {
+	return {
+		...threadView(thread),
+		read: thread.read,
+		snoozedUntil: iso(thread.snoozedUntil)
+	};
+}
+/**
+* Project one message.
+*
+* The threading internals — `mimeMessageId`, `mimeInReplyTo`, `mimeReferences`, `rawKey`, `rawBytes` —
+* are dropped. They are how a reply is stitched to its parent, and an operator would never act on one.
+* `rawKey` in particular is the R2 object holding the message exactly as it arrived, which is the one
+* copy of this data that has had nothing done to it.
+*/
+function messageView(message) {
+	return {
+		id: message.id,
+		direction: message.direction,
+		channel: message.channel,
+		context: message.context ?? null,
+		fromAddress: message.fromAddress ?? null,
+		fromName: message.fromName ?? null,
+		toAddress: message.toAddress ?? null,
+		subject: message.subject,
+		htmlBody: message.htmlBody ?? null,
+		textBody: message.textBody,
+		emailJobId: message.emailJobId ?? null,
+		receivedAt: message.receivedAt.toISOString()
+	};
+}
+/**
+* Project one thread for the person who opened it.
+*
+* **Built from scratch rather than from {@link threadView}, and that is the security boundary.** A
+* submitter's view derived by omitting fields from an operator's would disclose the next column
+* somebody adds, silently, on the day they add it — the failure would be a default rather than a
+* decision. Starting from nothing means a field reaches a customer only because somebody wrote it
+* here.
+*
+* So: no classification, no priority, no sentiment, no confidence, no model, no viewer flags, no
+* account link, no `archivedBy`, no addresses. What is left is their conversation.
+*/
+function myThreadView(thread) {
+	return {
+		id: thread.id,
+		subject: thread.subject,
+		resolved: thread.archived,
+		messageCount: thread.messageCount,
+		lastMessageAt: thread.lastMessageAt.toISOString(),
+		createdAt: thread.createdAt.toISOString()
+	};
+}
+/** Project one message for the person in the conversation. Their own attachments ride along. */
+function myMessageView(message, attachments) {
+	return {
+		id: message.id,
+		direction: message.direction,
+		body: message.textBody,
+		context: message.context ?? null,
+		attachments,
+		sentAt: message.receivedAt.toISOString()
+	};
+}
+/** Project the customer context beside a conversation. */
+function senderView(sender) {
+	return {
+		authenticated: sender.authenticated,
+		userId: sender.userId,
+		billingScope: "user",
+		...sender.name === void 0 ? {} : { name: sender.name },
+		...sender.emailVerified === void 0 ? {} : { emailVerified: sender.emailVerified },
+		purchases: sender.purchases.map((purchase) => ({
+			id: purchase.id,
+			rail: purchase.rail,
+			productId: purchase.productId,
+			status: purchase.status,
+			environment: purchase.environment,
+			purchasedAt: purchase.purchasedAt.toISOString(),
+			expiresAt: iso(purchase.expiresAt),
+			revokedAt: iso(purchase.revokedAt)
+		})),
+		entitlements: sender.entitlements.map((entitlement) => ({
+			key: entitlement.key,
+			active: entitlement.active,
+			expiresAt: iso(entitlement.expiresAt),
+			source: entitlement.source
+		}))
+	};
+}
+//#endregion
+export { listedThreadView, messageView, myMessageView, myThreadView, senderView, threadView };

package/dist/inbound/authenticity.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Whether a message's `From:` header is something we are entitled to believe.
+ *
+ * ## Why this exists
+ *
+ * `From:` is an unauthenticated claim. Anyone can send mail saying `From: ada@example.com`, and for
+ * every domain that publishes DMARC `p=none` — which is most small domains and plenty of large ones
+ * — a receiving MTA will deliver it rather than reject it.
+ *
+ * That claim is the join key for the customer link: it resolves to a `pithy_auth_users` row and
+ * pulls that account's name, entitlements, and itemized purchase history into a support console,
+ * where a human reads it and acts. Rendering an attacker's thread decorated with a real customer's
+ * billing history is the standard opening move of support-driven account takeover, and this
+ * capability's own `account_access` and `privacy_request` categories route exactly those messages to
+ * an operator already primed to act on them.
+ *
+ * The recipient side of this package gets the equivalent question right and says so at length: the
+ * SMTP envelope is authority, headers are not. This is that same rule applied to the sender.
+ *
+ * ## What counts as authenticated
+ *
+ * DMARC is the only verdict that asserts what we actually need — that the **`From:` domain** is
+ * aligned with something that passed. `spf=pass` alone says the *envelope* sender's domain passed,
+ * which is a different domain and is exactly the gap DMARC exists to close, so it counts only when
+ * the envelope sender aligns with the header From. `dkim=pass` alone has the same alignment gap.
+ *
+ * Absence is not a pass. A message with no `Authentication-Results` at all is unauthenticated, which
+ * is the right answer for mail that reached us through something that never checked.
+ */
+/** What is known about a sender's claimed identity. */
+export interface SenderAuthenticity {
+    /** Whether the `From:` header may be treated as the real sender. */
+    authenticated: boolean;
+    /** How it was established, for the log and for a dashboard to explain itself. `none` when it was not. */
+    method: "dmarc" | "spf-aligned" | "none";
+}
+/**
+ * Whether two domains are aligned in the relaxed sense DMARC uses — the same Organizational Domain.
+ *
+ * **This is a public-suffix lookup, not label arithmetic, because RFC 7489 §3.2 defines relaxed
+ * alignment in terms of the Organizational Domain and that term is defined by the public suffix
+ * list.** An earlier version counted labels and required a shared parent of at least two, which is a
+ * decent approximation and wrong in exactly the way approximations of security boundaries are wrong:
+ * `co.uk` has two labels, so it "aligned" with `bbc.co.uk`. Implementing the actual algorithm removes
+ * the whole class rather than the instance somebody happened to notice.
+ *
+ * `allowPrivateDomains` is on. Without it `a.github.io` and `b.github.io` both reduce to `github.io`
+ * and two unrelated people's sites align with each other; the private section of the list is what
+ * knows that `github.io` is a boundary. Stricter is the right direction for a check that gates
+ * whether a stranger's mail gets decorated with a real customer's purchase history.
+ *
+ * A domain that has no Organizational Domain at all — a bare public suffix like `co.uk`, an IP
+ * literal, `localhost` — returns `null` from `getDomain` and therefore aligns with nothing, which is
+ * the correct answer rather than a special case.
+ */
+export declare function domainsAlign(a: string | undefined, b: string | undefined): boolean;
+/**
+ * Decide whether the `From:` header is believable.
+ *
+ * Takes the parsed verdicts and both addresses rather than the whole message, so the decision is a
+ * pure function of four values and is testable without a MIME fixture.
+ */
+export declare function senderAuthenticity(options: {
+    /** The `Authentication-Results` verdicts, keyed by method. */
+    authResults: Record<string, string>;
+    /** The address in the `From:` header, normalized. */
+    fromAddress: string;
+    /** The SMTP envelope sender — what SPF was actually evaluated against. */
+    envelopeFrom: string | undefined;
+    /**
+     * Whether the adopter has attested that the header is worth reading at all.
+     *
+     * **Default off, and this is the load-bearing gate.** Under Cloudflare Email Routing a Worker is
+     * not reliably given the MTA's own `Authentication-Results`, and a header the *sender* wrote is
+     * indistinguishable from one an MTA wrote once the MTA's copy is absent — so reading it by default
+     * would mean believing whatever the attacker typed. Everything below is a verdict about a value
+     * that only means something once somebody has said their pipeline produces it honestly.
+     */
+    trusted: boolean;
+}): SenderAuthenticity;
+//# sourceMappingURL=authenticity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authenticity.d.ts","sourceRoot":"","sources":["../../src/inbound/authenticity.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAC;IACvB,yGAAyG;IACzG,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;CAC1C;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAIlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;;;;;OAQG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,kBAAkB,CAcrB"}

package/dist/inbound/authenticity.js

@@ -0,0 +1,61 @@
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+import { getDomain } from "tldts";
+//#region src/inbound/authenticity.ts
+/** The domain half of an address, lowercased. */
+function domainOf(address) {
+	const normalized = parseAddress(address);
+	const at = normalized?.lastIndexOf("@") ?? -1;
+	return normalized && at > 0 ? normalized.slice(at + 1) : void 0;
+}
+/**
+* Whether two domains are aligned in the relaxed sense DMARC uses — the same Organizational Domain.
+*
+* **This is a public-suffix lookup, not label arithmetic, because RFC 7489 §3.2 defines relaxed
+* alignment in terms of the Organizational Domain and that term is defined by the public suffix
+* list.** An earlier version counted labels and required a shared parent of at least two, which is a
+* decent approximation and wrong in exactly the way approximations of security boundaries are wrong:
+* `co.uk` has two labels, so it "aligned" with `bbc.co.uk`. Implementing the actual algorithm removes
+* the whole class rather than the instance somebody happened to notice.
+*
+* `allowPrivateDomains` is on. Without it `a.github.io` and `b.github.io` both reduce to `github.io`
+* and two unrelated people's sites align with each other; the private section of the list is what
+* knows that `github.io` is a boundary. Stricter is the right direction for a check that gates
+* whether a stranger's mail gets decorated with a real customer's purchase history.
+*
+* A domain that has no Organizational Domain at all — a bare public suffix like `co.uk`, an IP
+* literal, `localhost` — returns `null` from `getDomain` and therefore aligns with nothing, which is
+* the correct answer rather than a special case.
+*/
+function domainsAlign(a, b) {
+	if (!a || !b) return false;
+	const organizational = getDomain(a, { allowPrivateDomains: true });
+	return organizational !== null && organizational === getDomain(b, { allowPrivateDomains: true });
+}
+/**
+* Decide whether the `From:` header is believable.
+*
+* Takes the parsed verdicts and both addresses rather than the whole message, so the decision is a
+* pure function of four values and is testable without a MIME fixture.
+*/
+function senderAuthenticity(options) {
+	if (!options.trusted) return {
+		authenticated: false,
+		method: "none"
+	};
+	if (options.authResults.dmarc === "pass") return {
+		authenticated: true,
+		method: "dmarc"
+	};
+	if (options.authResults.spf === "pass") {
+		if (domainsAlign(domainOf(options.envelopeFrom), domainOf(options.fromAddress))) return {
+			authenticated: true,
+			method: "spf-aligned"
+		};
+	}
+	return {
+		authenticated: false,
+		method: "none"
+	};
+}
+//#endregion
+export { domainsAlign, senderAuthenticity };