@pithy-sh/support 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,272 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { requireSameOrigin } from "@pithy-sh/core/src/http/sameOrigin";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import { requireAuth } from "./guards";
+import {
+  archiveConversation,
+  type HandlerDeps,
+  listInbox,
+  listMyThreads,
+  listReplies,
+  readConversation,
+  readMyThread,
+  reclassifyConversation,
+  replyToConversation,
+  submitFeedbackRequest,
+  updateFlags,
+} from "./handlers";
+import type { SupportRepliesResponse } from "./responses";
+import {
+  ArchiveThreadInput,
+  FlagsInput,
+  ListThreadsQuery,
+  MyThreadsQuery,
+  RepliesQuery,
+  ReplyInput,
+  SubmitFeedbackInput,
+  ThreadIdParam,
+} from "./schemas";
+import {
+  SUPPORT_THREADS_ARCHIVE_SCOPE,
+  SUPPORT_THREADS_FLAG_SCOPE,
+  SUPPORT_THREADS_READ_SCOPE,
+  SUPPORT_THREADS_RECLASSIFY_SCOPE,
+  SUPPORT_THREADS_REPLY_SCOPE,
+} from "./scopes";
+
+/**
+ * The support routes, their verification strategies, and what each accepts:
+ *
+ *   GET  /support/threads               → the inbox     (control-plane: support:threads:read)       query: ListThreadsQuery
+ *   GET  /support/threads/:id           → one thread    (control-plane: support:threads:read)       param: ThreadIdParam
+ *   POST /support/threads/:id/archive   → done/reopen   (control-plane: support:threads:archive)    param + json
+ *   POST /support/threads/:id/reply     → answer        (control-plane: support:threads:reply)      param + json
+ *   POST /support/threads/:id/reclassify→ re-run model  (control-plane: support:threads:reclassify) param
+ *   POST /support/threads/:id/flags     → read/snooze   (control-plane: support:threads:flag)       param + json
+ *   GET  /support/replies               → canned copy   (control-plane: support:threads:read)       query: RepliesQuery
+ *
+ *   POST /support/feedback              → write in      (bearer/session + same-origin)              json: SubmitFeedbackInput
+ *   GET  /support/feedback              → my requests   (bearer/session)                            query: MyThreadsQuery
+ *   GET  /support/feedback/:id          → one of mine   (bearer/session)                            param: ThreadIdParam
+ *
+ * **Two surfaces, two gates, and they never stack.** The management routes answer to a control-plane
+ * credential the adopter issued, and with the seam uncomposed every one denies with
+ * `controlplane/not_connected` — the correct failure for an inbox holding other people's private
+ * correspondence. The `feedback` routes answer to the adopter's own signed-in user, and with no auth
+ * capability composed `c.var.auth` is null and every one denies. A control-plane caller holds no
+ * session by design and can never satisfy `requireAuth()`; a user's session confers no scope. See
+ * `guards.ts`.
+ *
+ * **`requireSameOrigin()` is on the submission route and on neither read.** Cookie-mode sessions make a
+ * mutating route CSRF-reachable, and this one writes into a support inbox under a real customer's name
+ * — a forged submission is somebody else's words attributed to them, in the one place an operator
+ * treats attribution as proven. The reads are GETs and carry no such risk. A bearer caller is
+ * CSRF-exempt, and that exemption belongs to the gate `@pithy-sh/auth` publishes rather than to
+ * anything decided here.
+ *
+ * **Every response has an exported schema**, in `responses.ts`. Each handler's return type is
+ * `z.output` of its envelope, so `c.json(await handler(...))` carries the contract without a cast — and
+ * a management client imports the same object and validates with it rather than hand-writing a mirror
+ * that drifts.
+ *
+ * The validators sit **after** the gate on every line. A validator ahead of it turns a 401 into a
+ * 400 and tells an unverified caller which requests were well-formed — and on this surface that is a
+ * live oracle for the shape of an adopter's support tooling.
+ *
+ * ## An adopter's own authorization on the submission route
+ *
+ * **This capability gates `POST {base}/feedback` on a session and same-origin, and on nothing else,
+ * permanently.** Writing to support must not be role-gated or it stops being a general intake: the
+ * person who most needs to reach support is often the one whose access is broken, and a role the kit
+ * invented would make one adopter's account model a condition on everybody's ability to report a bug.
+ *
+ * But an adopter whose *own* model makes some submissions act-on-behalf-of — `pithy-sh/dashboard#10`'s
+ * discount application is made for an organization, and a member may not make one — needs somewhere to
+ * put that check, and it must not be the client. **The seam for it already exists, in the composition
+ * contract rather than in this capability's config**, and it is documented here because it was not
+ * discoverable rather than because it was missing:
+ *
+ * ```ts
+ * // the adopter's own `app` capability
+ * defineCapability({
+ *   name: "app",
+ *   middleware: [
+ *     (app) => {
+ *       app.use("/support/feedback", async (c, next) => {
+ *         // c.var.auth is already populated — @pithy-sh/auth's session middleware is a library's, and
+ *         // every capability's middleware mounts before any capability's routes.
+ *         if (c.var.auth && !(await mayWriteOnBehalfOfTheOrganization(c))) throw new ForbiddenError({ … });
+ *         await next();
+ *       });
+ *     },
+ *   ],
+ *   …
+ * });
+ * ```
+ *
+ * `createBackend` mounts **every** capability's middleware before **any** capability's routes, and the
+ * adopter's `app` capability composes last — so their middleware runs after auth has resolved the
+ * session and before this file's `requireAuth()`. `createBackend.workers.test.ts` pins that ordering,
+ * because a paragraph asserting it is not the same as a test failing when it changes.
+ *
+ * Two consequences worth stating rather than discovering. Their middleware sees `c.var.auth` as **null**
+ * on an unauthenticated request, since it runs ahead of the route's own gate — so it should pass those
+ * through and let `requireAuth()` answer 401, rather than 403 a caller who was never signed in. And the
+ * path is theirs to write, from the `basePath` they configured; a mount point they changed and a
+ * middleware path they did not is a gate that silently stops covering anything.
+ *
+ * **A `beforeSubmit` callback in `SupportConfig` was the tempting alternative and is the wrong shape.**
+ * The need is not support's — every capability with a write route has it — so solving it once per
+ * capability would give an adopter a different mechanism per package, each with its own signature and
+ * its own answer to "what is in scope here". A config file is also the wrong home for an authorization
+ * decision that wants `c.var`, and a second place to look for the gates on a route is how a Worker ends
+ * up with two of them, free to disagree.
+ */
+
+/** How the support sub-router is built. */
+export interface SupportRoutesOptions {
+  /** The path the routes mount under. Defaults to `/support`. */
+  basePath?: string;
+  /**
+   * Whether to mount the in-app submission routes. Defaults to true, matching `submission.enabled`.
+   *
+   * Not mounting is deliberate rather than a guard inside the handlers: a route that is not served
+   * answers 404, and 404 is the honest answer. A 403 would say "this exists and you may not use it" to
+   * a caller asking about a feature this deployment does not have.
+   */
+  submission?: boolean;
+  /** Resolve handler deps from the request context. */
+  resolveDeps: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
+}
+
+/**
+ * The verified management client behind a control-plane call.
+ *
+ * `requireControlPlane()` has run on every route, so `c.var.controlPlane` is populated by the time a
+ * handler reads it. The throw is a programming-error guard, not a runtime path: reaching it would
+ * mean a route was mounted without its gate, which is the one mistake this whole file is arranged to
+ * make impossible.
+ */
+function viewer(c: Context<PithyHonoEnv>): string {
+  const subject = c.var.controlPlane?.subject;
+  if (!subject) {
+    throw new InternalError({
+      message: "Support could not identify the management caller.",
+      detail: "requireControlPlane() must run before a support handler reads the caller.",
+    });
+  }
+  return subject;
+}
+
+/**
+ * The signed-in user behind an in-app submission.
+ *
+ * `requireAuth()` has run on every route that calls this, so `c.var.auth` is populated by the time a
+ * handler reads it. The throw is a programming-error guard rather than a runtime path — the mirror of
+ * {@link viewer}, and the reason neither handler ever has to think about an absent caller.
+ */
+function submitter(c: Context<PithyHonoEnv>): string {
+  const auth = c.var.auth;
+  if (!auth) {
+    throw new InternalError({
+      message: "Support could not identify the signed-in caller.",
+      detail: "requireAuth() must run before a support submission handler reads the submitter.",
+    });
+  }
+  return auth.userId;
+}
+
+/** Register the support sub-router. Returned as the capability's `routes` hook. */
+export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/support";
+  const resolve = options.resolveDeps;
+  const submission = options.submission ?? true;
+
+  return (app) => {
+    app.get(
+      `${base}/threads`,
+      requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
+      zValidator("query", ListThreadsQuery, validationHook),
+      async (c) => c.json(await listInbox(await resolve(c), c.req.valid("query"), viewer(c))),
+    );
+
+    app.get(
+      `${base}/replies`,
+      requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
+      zValidator("query", RepliesQuery, validationHook),
+      async (c) =>
+        c.json({ replies: listReplies(await resolve(c), c.req.valid("query")) } satisfies SupportRepliesResponse),
+    );
+
+    app.get(
+      `${base}/threads/:id`,
+      requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
+      zValidator("param", ThreadIdParam, validationHook),
+      async (c) => c.json(await readConversation(await resolve(c), c.req.valid("param").id)),
+    );
+
+    app.post(
+      `${base}/threads/:id/archive`,
+      requireControlPlane(SUPPORT_THREADS_ARCHIVE_SCOPE),
+      zValidator("param", ThreadIdParam, validationHook),
+      zValidator("json", ArchiveThreadInput, validationHook),
+      async (c) =>
+        c.json(await archiveConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c))),
+    );
+
+    app.post(
+      `${base}/threads/:id/reply`,
+      requireControlPlane(SUPPORT_THREADS_REPLY_SCOPE),
+      zValidator("param", ThreadIdParam, validationHook),
+      zValidator("json", ReplyInput, validationHook),
+      async (c) =>
+        c.json(
+          await replyToConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c)),
+          201,
+        ),
+    );
+
+    app.post(
+      `${base}/threads/:id/reclassify`,
+      requireControlPlane(SUPPORT_THREADS_RECLASSIFY_SCOPE),
+      zValidator("param", ThreadIdParam, validationHook),
+      async (c) => c.json(await reclassifyConversation(await resolve(c), c.req.valid("param").id, viewer(c))),
+    );
+
+    app.post(
+      `${base}/threads/:id/flags`,
+      requireControlPlane(SUPPORT_THREADS_FLAG_SCOPE),
+      zValidator("param", ThreadIdParam, validationHook),
+      zValidator("json", FlagsInput, validationHook),
+      async (c) => c.json(await updateFlags(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c))),
+    );
+
+    if (!submission) return;
+
+    // The one route on this capability a customer calls directly. `requireAuth()` first, then the CSRF
+    // gate, then the contract — a validator ahead of either would turn a 401 into a 400 and tell an
+    // unauthenticated caller which submissions were well-formed.
+    app.post(
+      `${base}/feedback`,
+      requireAuth(),
+      requireSameOrigin(),
+      zValidator("json", SubmitFeedbackInput, validationHook),
+      async (c) => c.json(await submitFeedbackRequest(await resolve(c), c.req.valid("json"), submitter(c)), 201),
+    );
+
+    app.get(`${base}/feedback`, requireAuth(), zValidator("query", MyThreadsQuery, validationHook), async (c) =>
+      c.json(await listMyThreads(await resolve(c), c.req.valid("query"), submitter(c))),
+    );
+
+    app.get(`${base}/feedback/:id`, requireAuth(), zValidator("param", ThreadIdParam, validationHook), async (c) =>
+      c.json(await readMyThread(await resolve(c), c.req.valid("param").id, submitter(c))),
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,251 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MAX_SUBMISSION_ATTACHMENTS, MAX_SUBMISSION_BODY_CHARS, MAX_SUBMISSION_SUBJECT_CHARS } from "../config/config";
+import { SupportChannel, SupportPriority, SupportSentiment } from "../data/enums";
+import { SupportSubmissionContext } from "../data/message";
+import { MAX_PAGE_SIZE } from "../store/paging";
+
+/**
+ * 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. */
+export 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.");
+export type ThreadIdParam = z.infer<typeof ThreadIdParam>;
+
+/** 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. */
+export 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(MAX_PAGE_SIZE)
+      .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.");
+export type ListThreadsQuery = z.infer<typeof ListThreadsQuery>;
+
+/** The archive/unarchive body. */
+export 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.");
+export type ArchiveThreadInput = z.infer<typeof ArchiveThreadInput>;
+
+/** The reply body. */
+export const ReplyInput = z
+  .object({
+    body: z
+      .string()
+      .min(1)
+      .max(50_000)
+      .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.");
+export type ReplyInput = z.infer<typeof ReplyInput>;
+
+/** The per-viewer flags body. */
+export 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.");
+export type FlagsInput = z.infer<typeof FlagsInput>;
+
+/**
+ * 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.
+ */
+export 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
+      // **Both alphabets, and the union is not belt-and-braces.** `z.base64()` rejects any string
+      // containing `-` or `_`, so it alone would 400 every client whose platform encoder emits
+      // `base64url` — Swift's `base64EncodedString(options:)`, Node's `toString("base64url")`, and
+      // most JWT-adjacent helpers — while `decodeBase64` sits behind it happily normalizing the two.
+      // A validator that refuses what the decoder documents as fine is the validator that is wrong.
+      .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.");
+export type SubmittedAttachmentInput = z.infer<typeof SubmittedAttachmentInput>;
+
+/**
+ * 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.
+ */
+export const SubmitFeedbackInput = z
+  .object({
+    subject: z
+      .string()
+      .min(1)
+      .max(MAX_SUBMISSION_SUBJECT_CHARS)
+      .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(MAX_SUBMISSION_ATTACHMENTS)
+      .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.");
+export type SubmitFeedbackInput = z.infer<typeof SubmitFeedbackInput>;
+
+/** The submitter's own thread list. */
+export 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(MAX_PAGE_SIZE)
+      .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.",
+  );
+export type MyThreadsQuery = z.infer<typeof MyThreadsQuery>;
+
+/** The canned-reply catalog query. */
+export 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.");
+export type RepliesQuery = z.infer<typeof RepliesQuery>;

package/src/http/scopes.ts

@@ -0,0 +1,117 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+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 const SUPPORT_THREADS_READ_SCOPE: ControlPlaneScope = "support:threads:read";
+
+/** Mark a thread done or reopen it — the one shared piece of state in the model. */
+export const SUPPORT_THREADS_ARCHIVE_SCOPE: ControlPlaneScope = "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.
+ */
+export const SUPPORT_THREADS_REPLY_SCOPE: ControlPlaneScope = "support:threads:reply";
+
+/** Re-run the model over a thread, overwriting its current classification. */
+export const SUPPORT_THREADS_RECLASSIFY_SCOPE: ControlPlaneScope = "support:threads:reclassify";
+
+/** Set a viewer's own read/snooze flags. Private, uncoordinated, and the least dangerous thing here. */
+export const SUPPORT_THREADS_FLAG_SCOPE: ControlPlaneScope = "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.
+ */
+export const SUPPORT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  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.
+ */
+export function supportAdminRoutes(basePath: string): AdminRoute[] {
+  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.",
+    },
+  ];
+}