@pithy-sh/core 0.1.0

package/src/error/pithyError.ts

@@ -0,0 +1,281 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { MessageParams } from "../i18n/catalog";
+import type { ValidationIssue } from "./payload";
+import { ErrorPayload } from "./payload";
+
+/**
+ * `PithyError` is the one throw/catch vehicle. A thrown thing must be `instanceof Error`
+ * (for `catch`, stack traces, `cause`); a Zod object is a data shape, not an `Error`. So the
+ * class does not extend a schema — it **carries** one. The payload is validated against
+ * `ErrorPayload` at construction, so every `PithyError` in flight is either a member of the kit's
+ * closed taxonomy or an adopter's own code under a domain the kit does not reserve — nothing else
+ * gets thrown. The subclasses below are sugar that default a member's `code`/`status`; they set a
+ * payload the union already defines, so there is no second source of truth.
+ */
+export class PithyError extends Error {
+  readonly payload: ErrorPayload;
+
+  constructor(payload: ErrorPayload, options?: { cause?: unknown }) {
+    const parsed = ErrorPayload.parse(payload);
+    super(parsed.message, options);
+    this.payload = parsed;
+    this.name = "PithyError";
+  }
+}
+
+/** Variable parts every subclass accepts; the `code`/`status` are fixed by the subclass. */
+interface ErrorArgs {
+  /** Override the public, safe-to-expose message. Defaults to a per-code summary. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`. The `code` is the catalog
+   * key, so a throw site that fills a placeholder states it once, here.
+   */
+  params?: MessageParams;
+}
+
+export class ValidationError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "validation/invalid_input" }>;
+
+  constructor(args: ErrorArgs & { issues?: ValidationIssue[] } = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "validation/invalid_input",
+        status: 400,
+        message: args.message ?? "Invalid input.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+        issues: args.issues ?? [],
+      },
+      options,
+    );
+  }
+}
+
+export class UnauthorizedError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "auth/invalid_token" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "auth/invalid_token",
+        status: 401,
+        message: args.message ?? "Invalid or expired credentials.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * One code for every way a `signed-webhook` delivery fails to prove its origin. The step that failed
+ * goes in `detail`, which the HTTP codec strips — a forger learns only that it failed, and an operator
+ * reading the log learns which check refused it.
+ */
+export class WebhookUnverifiedError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/webhook_unverified" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/webhook_unverified",
+        status: 401,
+        message: args.message ?? "That delivery could not be verified.",
+        action: args.action ?? "Sign the request with this endpoint's current secret and send it promptly.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class ForbiddenError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "auth/forbidden" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "auth/forbidden",
+        status: 403,
+        message: args.message ?? "Forbidden.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class NotFoundError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/not_found" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/not_found",
+        status: 404,
+        message: args.message ?? "Not found.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class ConflictError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/conflict" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/conflict",
+        status: 409,
+        message: args.message ?? "Conflict.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class RateLimitError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "rate_limit/exceeded" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rate_limit/exceeded",
+        status: 429,
+        message: args.message ?? "Too many requests.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class InternalError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/internal" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/internal",
+        status: 500,
+        message: args.message ?? "Something unexpected happened.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * A service this one depends on and does not control failed. Reach for this — never `InternalError`
+ * — whenever the thing that broke sits behind a network call: a proxied request, a REST client, a
+ * provider. A 500 tells the operator to read *our* logs, and for an upstream outage that is the
+ * wrong system. The endpoint and the upstream's own status belong in `detail`.
+ */
+export class UpstreamError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/upstream_failed" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/upstream_failed",
+        status: 502,
+        message: args.message ?? "An upstream service could not be reached.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The same dependency, out of time rather than answered. Retryable, and possibly already applied. */
+export class UpstreamTimeoutError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/upstream_timeout" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/upstream_timeout",
+        status: 504,
+        message: args.message ?? "An upstream service did not answer in time.",
+        action: args.action ?? "Try again in a moment.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * Map a `ZodError` to a `validation/invalid_input` `PithyError`. Zod is the boundary validator
+ * everywhere (HTTP input, KV, env, D1 rows), so this is the most common error path — one place
+ * turns any failed parse into the typed family, carrying the field-level issues to the client.
+ */
+export function fromZodError(error: z.ZodError, args: ErrorArgs = {}): ValidationError {
+  const issues: ValidationIssue[] = error.issues.map((issue) => ({
+    path: issue.path.filter((segment): segment is string | number => typeof segment !== "symbol"),
+    message: issue.message,
+    code: issue.code,
+  }));
+  return new ValidationError({
+    message: args.message,
+    action: args.action,
+    detail: args.detail,
+    params: args.params,
+    issues,
+  });
+}
+
+/**
+ * The message of an unknown throw, for use as a `PithyError` `detail` — `error.message` for an
+ * `Error`, else its string form. One source of truth so every catch site that wants the cause text
+ * does it the same way (CLAUDE.md §Errors).
+ */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * One caught error as one sentence for a human: its {@link messageOf}, then its `action` when it has
+ * one. For a caller that has to *report* a failure rather than re-throw it — a CLI check that must keep
+ * running, a diagnostic that collects several.
+ *
+ * **Both halves, because they answer different questions**: the message says what is wrong and where,
+ * the action says what to do about it. A reporter that keeps only the message drops the fix.
+ *
+ * **Never `detail`.** That is throw-site context, deliberately stripped at the HTTP boundary, and a
+ * string built here is printed to a terminal and pasted into issues. Same rule, one line up.
+ */
+export function sentenceOf(error: unknown): string {
+  const action = error instanceof PithyError ? error.payload.action : undefined;
+  return action ? `${messageOf(error)} ${action}` : messageOf(error);
+}

package/src/error/terminal.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ErrorPayload } from "./payload";
+import { PublicErrorPayload } from "./payload";
+
+/**
+ * Render an error for the terminal: the public `message` becomes the problem line and the
+ * optional `action` the action line — the two-line brand-voice shape `docs/CLI.md` §3.3 specifies.
+ * This unifies the CLI's error output into the one `PithyError` family: the CLI catches a
+ * `PithyError`, colorizes the first line via its `style.ts`, and prints this. `detail` is internal
+ * and never rendered. The same payload that encodes to HTTP renders here — one error, two surfaces.
+ */
+export function renderTerminal(payload: ErrorPayload): string {
+  return payload.action ? `${payload.message}\n${payload.action}` : payload.message;
+}
+
+/** An error as an operator's machine surface states it: the wire fields, plus the remedy. */
+export type OperatorError = PublicErrorPayload & { action?: string };
+
+/**
+ * The machine-readable projection for an **operator's** consumer — the CLI's `--json` error line.
+ *
+ * The same audience as {@link renderTerminal}, in the shape a script can read. `action` belongs on it
+ * for the reason it belongs on the terminal: whoever runs `pithy secrets create --json` is the person
+ * who can act on "Bind a D1 database named DB in wrangler.jsonc". Dropping it because the *HTTP*
+ * surface must would be classifying the field by the encoder that happened to be reused rather than
+ * by who is reading.
+ *
+ * `detail` is still gone, and gone by the same schema that removes it on the wire — the public parse.
+ * One rule, applied twice, rather than a second rule here that could drift from the first.
+ */
+export function operatorError(payload: ErrorPayload): OperatorError {
+  const wire = PublicErrorPayload.parse(payload);
+  return payload.action === undefined ? wire : { ...wire, action: payload.action };
+}

package/src/http/authContext.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { Locale } from "../i18n/locale";
+
+/**
+ * The auth seam. `@pithy-sh/core` defines this shape; `@pithy-sh/auth` populates it on the
+ * request via the `bearer`/`session` strategies. Other capabilities depend only on this
+ * object (and `requireAuth`), never on auth internals.
+ *
+ * **`locale` rides here rather than being fetched**, because the session lookup has already loaded the
+ * user row and a second read of the same fact would be a query per request for a string auth is
+ * holding. It is the `user` link of `@pithy-sh/i18n`'s server chain — the one that makes a reader's
+ * stored choice outrank their device's `Accept-Language`. That link read `c.var.locale` at first,
+ * which nothing ever wrote, so it silently contributed nothing and the chain degraded to
+ * `param → cookie → header → default` while the docs said otherwise.
+ */
+export const AuthContext = z
+  .object({
+    userId: z.string().describe("ID of the authenticated user (populated by @pithy-sh/auth)."),
+    sessionId: z.string().describe("ID of the active session this request belongs to."),
+    scopes: z.array(z.string()).default([]).describe("Permission scopes granted to this session."),
+    locale: Locale.nullish().describe(
+      "The reader's own stored language, from `pithy_auth_users.locale`; null or absent when they have never chosen.",
+    ),
+  })
+  .describe("Per-request authenticated identity; the seam other capabilities depend on.");
+export type AuthContext = z.infer<typeof AuthContext>;

package/src/http/routeContract.ts

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context, Hono, Next } from "hono";
+
+/**
+ * Gate 2 of the route request contract (issue #74). Its sibling, the `no-raw-request-input` Biome
+ * plugin, covers query and body: with `c.req.query()` and `c.req.json()` unavailable, the only way
+ * to read either is `c.req.valid()`, which only exists once a validator declared it. Path params
+ * have no such chokepoint — a handler can always reach one through a validator it never declared —
+ * so they need a positive check instead of a ban, and this is it.
+ *
+ * A composed app is the only place the answer lives: `Capability.routes` registers onto the app it
+ * is handed, so nothing static can see the finished route table. `app.routes` can — it carries one
+ * entry per registered handler, in order, with the path pattern intact.
+ *
+ * Identifying a param validator is the awkward part. `@hono/zod-validator` returns the same
+ * anonymous closure whatever its target, so there is nothing to inspect: no name, no property, no
+ * distinguishing shape. What does differ is *behavior* — `hono/validator` reads `c.req.param()`
+ * for the `param` target and nothing else does. So each middleware is invoked once against a probe
+ * context that records which accessor it touched. It is a real call, which is why only middleware
+ * are probed (never the terminal handler) and why every throw is swallowed: a guard meeting an
+ * empty context is expected to reject, and a validator meeting empty params is expected to fail
+ * validation. Either way the flag has already been set or not.
+ */
+
+/** One route that reads path params without declaring a schema for them. */
+export interface UncoveredRoute {
+  /** HTTP method as Hono records it (`GET`, `POST`, `ALL`, …). */
+  method: string;
+  /** The registered path pattern, e.g. `/leaderboard/:board/entries/:userId`. */
+  path: string;
+  /** The `:segment` names the path declares. */
+  params: string[];
+}
+
+/** The `:segment` names in a path pattern, in order. */
+export function pathParams(path: string): string[] {
+  return [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1] as string);
+}
+
+/**
+ * A context that answers every accessor `hono/validator` reaches for, and records the one that
+ * identifies a `param` validator. Deliberately minimal: anything a real guard reads is absent, so
+ * a guard rejects immediately instead of doing work.
+ */
+function probeContext(record: () => void) {
+  const req = {
+    param: () => {
+      record();
+      return {};
+    },
+    queries: () => ({}),
+    query: () => ({}),
+    header: (name?: string) => (name === undefined ? {} : undefined),
+    json: async () => ({}),
+    parseBody: async () => ({}),
+    arrayBuffer: async () => new ArrayBuffer(0),
+    valid: () => ({}),
+    addValidatedData: () => {},
+    bodyCache: {},
+    url: "http://route-contract.probe/",
+    raw: new Request("http://route-contract.probe/"),
+  };
+  return { req, env: {}, var: {}, get: () => undefined, set: () => {} } as unknown as Context;
+}
+
+/** Does this middleware read `c.req.param()` — i.e. is it a `zValidator("param", …)`? */
+async function readsPathParams(handler: (c: Context, next: Next) => unknown): Promise<boolean> {
+  let read = false;
+  try {
+    await handler(
+      probeContext(() => {
+        read = true;
+      }),
+      (async () => {}) as Next,
+    );
+  } catch {
+    // Expected: a guard rejects an empty context, a validator rejects empty params. Both are fine —
+    // whether `c.req.param()` was reached has already been decided by the time anything throws.
+  }
+  return read;
+}
+
+/**
+ * Every route on this app that declares a `:segment` but registers no param validator for it.
+ * An empty array is the contract being met. Feed it a composed app — one that every capability's
+ * `routes` has already been applied to.
+ */
+export async function uncoveredParamRoutes(app: Hono<never>): Promise<UncoveredRoute[]> {
+  const grouped = new Map<string, { method: string; path: string; handlers: ((c: Context, n: Next) => unknown)[] }>();
+  for (const route of app.routes) {
+    const key = `${route.method} ${route.path}`;
+    const entry = grouped.get(key) ?? { method: route.method, path: route.path, handlers: [] };
+    entry.handlers.push(route.handler as (c: Context, n: Next) => unknown);
+    grouped.set(key, entry);
+  }
+
+  const uncovered: UncoveredRoute[] = [];
+  for (const { method, path, handlers } of grouped.values()) {
+    const params = pathParams(path);
+    if (params.length === 0) continue;
+    // The last entry is the route's own handler; probing it would run real business logic.
+    const middleware = handlers.slice(0, -1);
+    let covered = false;
+    for (const handler of middleware) {
+      if (await readsPathParams(handler)) {
+        covered = true;
+        break;
+      }
+    }
+    if (!covered) uncovered.push({ method, path, params });
+  }
+  return uncovered;
+}

package/src/http/sameOrigin.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { ForbiddenError } from "../error/pithyError";
+
+/**
+ * The same-origin seam — one CSRF decision per Worker, made where the origins are known.
+ *
+ * ## Why the gate arrives already bound
+ *
+ * The origins a cookie-authenticated mutation may come from are the composed auth capability's:
+ * its `baseURL` plus its `trustedOrigins`. An adopter's own routes need the same rule, and the
+ * `routes` hook hands them only the Hono app — so the only way to write the check beside auth's own
+ * was to rebuild it from the request and hope the two agreed. They are free not to, and a Worker with
+ * two same-origin implementations has the weaker one as its actual policy.
+ *
+ * So the capability that resolved the origins publishes the gate **already bound** to them, and
+ * {@link requireSameOrigin} takes no argument. There is no origin list to pass, therefore no wrong one
+ * to pass — which is the failure mode, not the ceremony of passing it.
+ *
+ * The alternative considered was handing resolved capability config to the `routes` hook. That serves
+ * more cases (a base path, a rail toggle) and is worse here: it hands every adopter the raw material
+ * for a second, differently-bound copy of a security decision, which is the thing being removed.
+ *
+ * ## It fails closed
+ *
+ * With no capability publishing a policy the gate denies, exactly as `requireEntitlement` does with no
+ * provider composed. A gate that arrives with a package must not stand open when that package is
+ * absent; the denial names the reason in `detail`, where an operator reads it and a client does not.
+ */
+
+/**
+ * A same-origin gate, already bound to the origins the composing capability resolved. Published on
+ * `c.var.sameOrigin`, consumed by {@link requireSameOrigin}, and null when nothing published one.
+ *
+ * Deliberately a bound middleware rather than the origin list: a list on the request context is an
+ * invitation to build a second checker beside the first, and the point of the seam is that there is
+ * one.
+ */
+export type SameOriginGate = MiddlewareHandler<PithyHonoEnv>;
+
+/**
+ * Require this request to come from an origin the Worker trusts — the CSRF gate a cookie-authenticated
+ * mutating route wears, beside the strategy that says who the caller is.
+ *
+ *   app.post("/organizations", requireAuth(), requireSameOrigin(), zValidator(…), handler)
+ *
+ * A bearer request carries no ambient credential and is CSRF-exempt; that exemption belongs to the
+ * published gate, since the capability that owns the credential model is the one that knows.
+ */
+export function requireSameOrigin(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    const gate = c.var.sameOrigin;
+    if (!gate) {
+      throw new ForbiddenError({
+        message: "Cross-origin request rejected.",
+        action: "Compose a capability that resolves this Worker's trusted origins (auth), then retry.",
+        detail: "no same-origin policy on the request — no composed capability published one",
+      });
+    }
+    // `return await`, not `await`: a gate may answer by *returning* a Response rather than throwing,
+    // and a wrapper that swallowed it would leave the request unanswered — a refusal reported as a 500.
+    return await gate(c, next);
+  };
+}