@pithy-sh/core 0.1.2 → 0.1.4

package/dist/error/pithyError.d.ts

@@ -0,0 +1,154 @@
+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 declare class PithyError extends Error {
+    readonly payload: ErrorPayload;
+    constructor(payload: ErrorPayload, options?: {
+        cause?: unknown;
+    });
+}
+/** 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 declare class ValidationError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "validation/invalid_input";
+    }>;
+    constructor(args?: ErrorArgs & {
+        issues?: ValidationIssue[];
+    }, options?: {
+        cause?: unknown;
+    });
+}
+export declare class UnauthorizedError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "auth/invalid_token";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class WebhookUnverifiedError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/webhook_unverified";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class ForbiddenError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "auth/forbidden";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class NotFoundError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/not_found";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class ConflictError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/conflict";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class RateLimitError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "rate_limit/exceeded";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class InternalError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/internal";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class UpstreamError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/upstream_failed";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** The same dependency, out of time rather than answered. Retryable, and possibly already applied. */
+export declare class UpstreamTimeoutError extends PithyError {
+    readonly payload: Extract<ErrorPayload, {
+        code: "core/upstream_timeout";
+    }>;
+    constructor(args?: ErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function fromZodError(error: z.ZodError, args?: ErrorArgs): ValidationError;
+/**
+ * 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 declare function messageOf(error: unknown): string;
+/**
+ * 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 declare function sentenceOf(error: unknown): string;
+export {};
+//# sourceMappingURL=pithyError.d.ts.map

package/dist/error/pithyError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pithyError.d.ts","sourceRoot":"","sources":["../../src/error/pithyError.ts"],"names":[],"mappings":"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"}

package/dist/error/pithyError.js

@@ -0,0 +1,197 @@
+import { ErrorPayload } from "./payload.js";
+//#region src/error/pithyError.ts
+/**
+* `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.
+*/
+var PithyError = class extends Error {
+	payload;
+	constructor(payload, options) {
+		const parsed = ErrorPayload.parse(payload);
+		super(parsed.message, options);
+		this.payload = parsed;
+		this.name = "PithyError";
+	}
+};
+var ValidationError = class extends PithyError {
+	constructor(args = {}, options) {
+		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);
+	}
+};
+var UnauthorizedError = class extends PithyError {
+	constructor(args = {}, options) {
+		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.
+*/
+var WebhookUnverifiedError = class extends PithyError {
+	constructor(args = {}, options) {
+		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);
+	}
+};
+var ForbiddenError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "auth/forbidden",
+			status: 403,
+			message: args.message ?? "Forbidden.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var NotFoundError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "core/not_found",
+			status: 404,
+			message: args.message ?? "Not found.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var ConflictError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "core/conflict",
+			status: 409,
+			message: args.message ?? "Conflict.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var RateLimitError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "rate_limit/exceeded",
+			status: 429,
+			message: args.message ?? "Too many requests.",
+			action: args.action,
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var InternalError = class extends PithyError {
+	constructor(args = {}, options) {
+		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`.
+*/
+var UpstreamError = class extends PithyError {
+	constructor(args = {}, options) {
+		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. */
+var UpstreamTimeoutError = class extends PithyError {
+	constructor(args = {}, options) {
+		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.
+*/
+function fromZodError(error, args = {}) {
+	const issues = error.issues.map((issue) => ({
+		path: issue.path.filter((segment) => 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).
+*/
+function messageOf(error) {
+	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.
+*/
+function sentenceOf(error) {
+	const action = error instanceof PithyError ? error.payload.action : void 0;
+	return action ? `${messageOf(error)} ${action}` : messageOf(error);
+}
+//#endregion
+export { ConflictError, ForbiddenError, InternalError, NotFoundError, PithyError, RateLimitError, UnauthorizedError, UpstreamError, UpstreamTimeoutError, ValidationError, WebhookUnverifiedError, fromZodError, messageOf, sentenceOf };

package/dist/error/terminal.d.ts

@@ -0,0 +1,28 @@
+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 declare function renderTerminal(payload: ErrorPayload): string;
+/** 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 declare function operatorError(payload: ErrorPayload): OperatorError;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/error/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/error/terminal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAGlE"}

package/dist/error/terminal.js

@@ -0,0 +1,33 @@
+import { PublicErrorPayload } from "./payload.js";
+//#region src/error/terminal.ts
+/**
+* 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.
+*/
+function renderTerminal(payload) {
+	return payload.action ? `${payload.message}\n${payload.action}` : payload.message;
+}
+/**
+* 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.
+*/
+function operatorError(payload) {
+	const wire = PublicErrorPayload.parse(payload);
+	return payload.action === void 0 ? wire : {
+		...wire,
+		action: payload.action
+	};
+}
+//#endregion
+export { operatorError, renderTerminal };

package/dist/http/authContext.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * 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 declare const AuthContext: z.ZodObject<{
+    userId: z.ZodString;
+    sessionId: z.ZodString;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type AuthContext = z.infer<typeof AuthContext>;
+//# sourceMappingURL=authContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authContext.d.ts","sourceRoot":"","sources":["../../src/http/authContext.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW;;;;;iBASiE,CAAC;AAC1F,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/http/authContext.js

@@ -0,0 +1,23 @@
+import { Locale } from "../i18n/locale.js";
+import { z } from "zod";
+//#region src/http/authContext.ts
+/**
+* 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.
+*/
+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.");
+//#endregion
+export { AuthContext };

package/dist/http/routeContract.d.ts

@@ -0,0 +1,39 @@
+import type { Hono } 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 declare function pathParams(path: string): string[];
+/**
+ * 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 declare function uncoveredParamRoutes(app: Hono<never>): Promise<UncoveredRoute[]>;
+//# sourceMappingURL=routeContract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routeContract.d.ts","sourceRoot":"","sources":["../../src/http/routeContract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAW,IAAI,EAAQ,MAAM,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjD;AA6CD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAyBtF"}

package/dist/http/routeContract.js

@@ -0,0 +1,82 @@
+//#region src/http/routeContract.ts
+/** The `:segment` names in a path pattern, in order. */
+function pathParams(path) {
+	return [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1]);
+}
+/**
+* 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) {
+	return {
+		req: {
+			param: () => {
+				record();
+				return {};
+			},
+			queries: () => ({}),
+			query: () => ({}),
+			header: (name) => name === void 0 ? {} : void 0,
+			json: async () => ({}),
+			parseBody: async () => ({}),
+			arrayBuffer: async () => /* @__PURE__ */ new ArrayBuffer(0),
+			valid: () => ({}),
+			addValidatedData: () => {},
+			bodyCache: {},
+			url: "http://route-contract.probe/",
+			raw: new Request("http://route-contract.probe/")
+		},
+		env: {},
+		var: {},
+		get: () => void 0,
+		set: () => {}
+	};
+}
+/** Does this middleware read `c.req.param()` — i.e. is it a `zValidator("param", …)`? */
+async function readsPathParams(handler) {
+	let read = false;
+	try {
+		await handler(probeContext(() => {
+			read = true;
+		}), (async () => {}));
+	} catch {}
+	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.
+*/
+async function uncoveredParamRoutes(app) {
+	const grouped = /* @__PURE__ */ new Map();
+	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);
+		grouped.set(key, entry);
+	}
+	const uncovered = [];
+	for (const { method, path, handlers } of grouped.values()) {
+		const params = pathParams(path);
+		if (params.length === 0) continue;
+		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;
+}
+//#endregion
+export { pathParams, uncoveredParamRoutes };

package/dist/http/sameOrigin.d.ts

@@ -0,0 +1,47 @@
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+/**
+ * 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 declare function requireSameOrigin(): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=sameOrigin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sameOrigin.d.ts","sourceRoot":"","sources":["../../src/http/sameOrigin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAcnE"}