@gusnips/server 0.1.0

package/src/logger/serialize.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, it } from "vitest";
+import { errorReplacer } from "./serialize.ts";
+
+/** Serialize a log entry the way the logger does, and read the result back. */
+function entryFor(meta: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(meta, errorReplacer())) as Record<string, unknown>;
+}
+
+/** Serialize one error under an `error` key and hand back what that key became. */
+function serialized(err: unknown): Record<string, unknown> {
+  return entryFor({ error: err }).error as Record<string, unknown>;
+}
+
+describe("what an Error contributes to a log line", () => {
+  it("drops the webhook body and the signature a payment SDK hangs off its own error", () => {
+    // The real shape, measured off the pinned SDK rather than imagined: a payment vendor's
+    // signature-verification error has 25 own enumerable properties, and two of them are the
+    // request the caller sent us — `payload` is the entire unparsed webhook body and `header` is
+    // the signature it was checked against. The webhook route is unauthenticated by definition,
+    // so the loop that copied all 25 let anyone on the internet choose what went into the log.
+    // Named here for its shape rather than its origin; the field names ARE the evidence.
+    const err = Object.assign(new Error("No signatures found matching the expected signature"), {
+      type: "SignatureVerificationError",
+      raw: { message: "No signatures found matching the expected signature" },
+      rawType: undefined,
+      detail: undefined,
+      headers: { "connected-account": "acct_live_1", "idempotency-key": "idem_1" },
+      requestId: "req_abc123",
+      statusCode: 400,
+      userMessage: undefined,
+      advice_code: undefined,
+      charge: "ch_1",
+      code: undefined,
+      decline_code: undefined,
+      doc_url: undefined,
+      network_advice_code: undefined,
+      network_decline_code: undefined,
+      param: undefined,
+      payment_intent: { id: "pi_1", client_secret: "pi_1_secret_LEAKED" },
+      payment_method: { id: "pm_1", card: { last4: "4242", exp_year: 2031 } },
+      payment_method_type: "card",
+      request_log_url: "https://dashboard.example.com/logs/req_abc123",
+      setup_intent: undefined,
+      source: undefined,
+      user_message: undefined,
+      header: "t=1700000000,v1=deadbeefdeadbeef",
+      payload: '{"id":"evt_1","data":{"object":{"customer_email":"someone@example.com"}}}',
+    });
+
+    const line = JSON.stringify(serialized(err));
+
+    expect(line).not.toContain("someone@example.com");
+    expect(line).not.toContain("pi_1_secret_LEAKED");
+    expect(line).not.toContain("4242");
+    expect(line).not.toContain("acct_live_1");
+    // toEqual, not a key check: the point is that nothing ELSE came along either.
+    expect(serialized(err)).toEqual({
+      name: "Error",
+      message: "No signatures found matching the expected signature",
+      // `type` earns its place here: this vendor never sets `name`, so without it every one of
+      // its failures reads as a bare "Error" in the log.
+      type: "SignatureVerificationError",
+      statusCode: 400,
+      stack: err.stack,
+    });
+  });
+
+  it("drops the password a Redis client hangs off a failed AUTH", () => {
+    // A Redis client attaches `command = { name, args }` to a server-returned error, and an AUTH
+    // failure routes through that assignment — so the line an operator reads to find out why
+    // Redis is refusing them carried the credential that was refused.
+    const err = Object.assign(new Error("WRONGPASS invalid username-password pair"), {
+      command: { name: "auth", args: ["default", "hunter2-the-real-password"] },
+    });
+
+    expect(JSON.stringify(serialized(err))).not.toContain("hunter2");
+  });
+
+  it("drops the statement text Postgres hangs off a constraint violation", () => {
+    // Reproduced against Postgres 18: a CHECK violation raised inside a PL/pgSQL function sets
+    // `where` to the failing statement, literals included. pg is in every backend here, so this
+    // is the copy-loop's third vendor and the only one that is not optional.
+    const err = Object.assign(new Error("new row violates check constraint"), {
+      code: "23514",
+      severity: "ERROR",
+      constraint: "probe_card_ck",
+      schema: "public",
+      table: "probe_t",
+      where:
+        'SQL statement "INSERT INTO probe_t (email, card) ' +
+        "VALUES ('someone@example.com', '4242424242424242')\"\nPL/pgSQL function probe_fn() line 3",
+      internalQuery: "INSERT INTO probe_t (email, card) VALUES ('someone@example.com', '4242…')",
+      routine: "ExecConstraints",
+      file: "execMain.c",
+      line: "2081",
+    });
+
+    const line = serialized(err);
+
+    expect(JSON.stringify(line)).not.toContain("someone@example.com");
+    expect(JSON.stringify(line)).not.toContain("4242");
+    expect(line).toMatchObject({ code: "23514", severity: "ERROR", constraint: "probe_card_ck" });
+  });
+
+  it("keeps the Postgres DETAIL that names the key, and drops the one that is the whole row", () => {
+    // Two message forms, one field. A unique violation names only the key columns, which is the
+    // diagnostic this field is kept for. A CHECK or NOT NULL violation writes the ENTIRE failing
+    // row — every column, whatever the table holds. Both strings are verbatim from Postgres 18.
+    const unique = Object.assign(new Error("duplicate key value violates unique constraint"), {
+      code: "23505",
+      detail: "Key (slug)=(demo) already exists.",
+      constraint: "boards_slug_key",
+    });
+    expect(serialized(unique).detail).toBe("Key (slug)=(demo) already exists.");
+
+    const check = Object.assign(new Error("new row violates check constraint"), {
+      code: "23514",
+      detail: "Failing row contains (someone@example.com, 4242424242424242).",
+    });
+    const line = serialized(check);
+    expect(JSON.stringify(line)).not.toContain("someone@example.com");
+    // Not silence: the reader is told a DETAIL existed and why it is not here.
+    expect(String(line.detail)).toContain("row omitted");
+  });
+
+  it("drops the rejected input a zod 3 validation error echoes back", () => {
+    // Measured: in zod 3 `issues` is an own enumerable property and an issue can carry the value
+    // that was rejected (`received: "…"`), so the copy loop wrote caller input into the log. In
+    // zod 4 it is non-enumerable and never rode along at all — so dropping it costs nothing on
+    // the version this fleet runs, and is a fix on the version it does not.
+    const err = Object.assign(new Error("invalid input"), {
+      name: "ZodError",
+      issues: [{ code: "invalid_enum_value", path: ["role"], received: "SUPER-SECRET-VALUE" }],
+    });
+
+    expect(JSON.stringify(serialized(err))).not.toContain("SUPER-SECRET-VALUE");
+  });
+
+  it("keeps what a Postgres failure has to say", () => {
+    // Why the extras ride along at all: without `code` a unique violation is indistinguishable
+    // from a syntax error, and `constraint` is what names which uniqueness was violated.
+    const err = Object.assign(new Error("duplicate key value violates unique constraint"), {
+      code: "23505",
+      detail: "Key (slug)=(demo) already exists.",
+      hint: "Pick another slug.",
+      constraint: "workspaces_slug_key",
+      severity: "ERROR",
+    });
+
+    expect(serialized(err)).toMatchObject({
+      code: "23505",
+      detail: "Key (slug)=(demo) already exists.",
+      hint: "Pick another slug.",
+      constraint: "workspaces_slug_key",
+      severity: "ERROR",
+    });
+  });
+
+  it("keeps the fields our own error classes carry", () => {
+    const err = Object.assign(new Error("too many requests"), {
+      code: "QUOTA_EXCEEDED",
+      statusCode: 429,
+      status: 429,
+      messageKey: "errors.QUOTA_EXCEEDED",
+      params: { plan: "free" },
+      retryAfterSecs: 60,
+      retryAfter: 60,
+      kind: "rate-limit",
+      retryable: false,
+    });
+
+    expect(serialized(err)).toMatchObject({
+      code: "QUOTA_EXCEEDED",
+      statusCode: 429,
+      status: 429,
+      messageKey: "errors.QUOTA_EXCEEDED",
+      params: { plan: "free" },
+      retryAfterSecs: 60,
+      retryAfter: 60,
+      kind: "rate-limit",
+      retryable: false,
+    });
+  });
+
+  it("follows the cause chain, and allow-lists every link of it", () => {
+    // `cause` is non-enumerable, so it is invisible to the loop above and has to be added by
+    // hand. Each link goes back through the replacer, so a vendor error buried three deep is
+    // filtered the same as one at the top.
+    const root = Object.assign(new Error("WRONGPASS invalid username-password pair"), {
+      code: "WRONGPASS",
+      command: { name: "auth", args: ["default", "hunter2-the-real-password"] },
+    });
+    const middle = new Error("cache unavailable", { cause: root });
+    const top = new Error("could not load the board", { cause: middle });
+
+    const line = serialized(top);
+    const cause = line.cause as Record<string, unknown>;
+    const deeper = cause.cause as Record<string, unknown>;
+
+    expect(cause.message).toBe("cache unavailable");
+    expect(deeper.code).toBe("WRONGPASS");
+    expect(JSON.stringify(line)).not.toContain("hunter2");
+  });
+
+  it("narrows a cause that is not an Error, which is the shape this package itself creates", () => {
+    // `errorBoundary` wraps every non-Error throw as `new Error(toMessage(err), { cause: err })`,
+    // so in a Hono app the cause slot is exactly where an SDK's own rejection object lands — and a
+    // PostgREST client rejecting with a plain object is why that wrapper exists. Until this, the
+    // allow-list stopped at the Error: the wrapper was filtered, the object one level under it was
+    // copied whole, and the line reads as though the list had run.
+    const rejection = {
+      message: "invalid signature",
+      code: "PGRST301",
+      payload: '{"card":"4242424242424242"}',
+      header: "t=1,v1=deadbeef",
+    };
+
+    const line = serialized(new Error("invalid signature", { cause: rejection }));
+
+    expect(line.cause).toEqual({ message: "invalid signature", code: "PGRST301" });
+    expect(JSON.stringify(line)).not.toContain("4242");
+  });
+
+  it("survives a chain of plain-object causes that holds itself", () => {
+    // The Error branch has had this guard since it was written; the narrowing builds a new object
+    // and so needs its own, or a self-referencing rejection recurses until the stack ends — inside
+    // the log call, which is the one place that must never take the process down.
+    const inner: Record<string, unknown> = { code: "E_LOOP" };
+    inner.cause = inner;
+
+    const line = serialized(new Error("looped", { cause: inner }));
+    const cause = line.cause as Record<string, unknown>;
+
+    expect(cause.code).toBe("E_LOOP");
+    expect(cause.cause).toBe("[Circular]");
+  });
+
+  it("keeps the stack of an error class that defines toJSON, which stringify calls first", () => {
+    // `JSON.stringify` calls a value's own `toJSON()` BEFORE the replacer, so an error class that
+    // defines one never reached the Error branch at all: the line got whatever that method
+    // returns, which is shaped for the WIRE, and lost the stack and the cause. Seven backends
+    // define one on their error class, so `logger.error("x", { error: appErr })` wrote
+    // `{"error":{"error":{…}}}` — double-nested, no stack. Invisible, because it still looks
+    // like a log line.
+    class WireError extends Error {
+      code = "NOT_FOUND";
+      toJSON() {
+        return { error: { code: this.code, message: this.message } };
+      }
+    }
+
+    const line = serialized(new WireError("Workspace not found"));
+
+    expect(line).toMatchObject({ message: "Workspace not found", code: "NOT_FOUND" });
+    expect(String(line.stack)).toContain("Workspace not found");
+    expect(line).not.toHaveProperty("error");
+  });
+
+  it("shows what an AggregateError aggregated", () => {
+    // `errors` is non-enumerable too, so without this line the whole log entry for a failed
+    // Promise.any is the word "all failed". Each sub-error is allow-listed like any other.
+    const agg = new AggregateError(
+      [
+        Object.assign(new Error("primary refused"), { code: "ECONNREFUSED", port: 6379 }),
+        Object.assign(new Error("replica refused"), { code: "ECONNREFUSED" }),
+      ],
+      "every cache endpoint refused",
+    );
+
+    const line = serialized(agg);
+    const errors = line.errors as Array<Record<string, unknown>>;
+
+    expect(line.message).toBe("every cache endpoint refused");
+    expect(errors).toHaveLength(2);
+    expect(errors[0]).toMatchObject({ message: "primary refused", code: "ECONNREFUSED" });
+    // `port` is not on the list: nothing in twelve backends reads it off a caught error.
+    expect(errors[0]).not.toHaveProperty("port");
+  });
+
+  it("survives a circular reference instead of crashing the log call", () => {
+    // Both shapes: an error that is its own cause, and a plain object that holds itself. A
+    // JSON.stringify with neither guard throws, inside the log call, which is how a logger takes
+    // down the process it was reporting on.
+    const err = new Error("cycle");
+    err.cause = err;
+    const job: Record<string, unknown> = { id: "job_1" };
+    job.parent = job;
+
+    const entry = entryFor({ error: err, job });
+
+    expect((entry.error as Record<string, unknown>).cause).toBe("[Circular]");
+    expect((entry.job as Record<string, unknown>).parent).toBe("[Circular]");
+  });
+
+  it("stringifies a bigint instead of throwing", () => {
+    // JSON.stringify refuses a bigint outright ("Do not know how to serialize a BigInt"), so
+    // one row count off a driver that returns them would end the log call.
+    expect(entryFor({ rows: 9007199254740993n }).rows).toBe("9007199254740993");
+  });
+});

package/src/logger/serialize.ts

@@ -0,0 +1,202 @@
+/**
+ * The error serializer. This is the one file in `@gusnips/server` that exists because of an
+ * incident rather than because of duplication.
+ *
+ * Six backends shipped the same replacer, and it copied **every own enumerable property** off a
+ * caught Error into the log line. The comment beside the loop said it was there to pick up a
+ * Postgres `code`/`detail`/`hint`. What it actually picked up was whatever the SDK that threw had
+ * hung on the error — which for two vendors in use is the request the caller sent us.
+ */
+
+/**
+ * The own enumerable properties a log line keeps off an Error. An ALLOW-list, not a deny-list,
+ * because an SDK hangs its own INPUTS off the error it throws, and the list of words vendors use
+ * for that is open-ended:
+ *
+ * - **A payment SDK.** Its signature-verification error carries `payload` — the entire unparsed
+ *   webhook body — and `header`, the signature it was checked against. Measured on the pinned
+ *   version: that error has **25 own enumerable properties** and this list admits **4** of them
+ *   (`type`, `code`, `detail`, `statusCode`). Among the 21 dropped are `raw` (the whole error body)
+ *   and `headers`. A webhook route is unauthenticated by definition, so the old loop let anyone on
+ *   the internet write content of their choosing into the log by POSTing a junk signature.
+ * - **A Redis client.** A server-returned error carries `command = { name, args }`. On an AUTH
+ *   failure those args are the password — written to stdout at the exact moment an operator is
+ *   reading the log to find out why Redis is refusing them.
+ * - **Postgres.** A `DatabaseError` carries `where` and `internalQuery`, which hold **statement
+ *   text with its literals in it**. Reproduced against Postgres 18: a CHECK violation raised inside
+ *   a PL/pgSQL function set `where` to the failing INSERT, e-mail address and card number included.
+ *   pg is in every backend here, so this one was never vendor-specific.
+ *
+ * A deny-list would have had to know `payload`, `header`, `raw`, `command`, `where` and the next
+ * vendor's word for it, and it learns each one from an incident. This list only has to know ours.
+ *
+ * **Add a key when our own code reads it off a caught error.** Two on it have no reader and say so
+ * below; everything else was measured across twelve backends.
+ */
+const KEPT_ERROR_FIELDS: ReadonlySet<string> = new Set([
+  // Postgres and PostgREST diagnostics. `detail` is the pg driver's spelling, `details`
+  // PostgREST's. `hint` has no reader anywhere in the fleet — it is kept because the donor
+  // comment promises it by name and a Postgres HINT never carries a value, only a suggestion.
+  "code",
+  "detail",
+  "details",
+  "hint",
+  "constraint",
+  "severity",
+  // Our own error classes, and the classified failures the modules throw.
+  "statusCode",
+  "status",
+  "messageKey",
+  "params",
+  "retryAfterSecs",
+  // The same number under an SDK's spelling. Our house word is `retryAfterSecs`; one SDK in the
+  // fleet says `retryAfter`, and two call sites read it off the caught error — so without this a
+  // rate-limit line says it was rate-limited and not for how long.
+  "retryAfter",
+  "kind",
+  "retryable",
+  // Which vendor error this was. One vendor sets `type` and never sets `name`, so without this
+  // every failure from it logs as a bare "Error". Read off the SDK, not guessed.
+  "type",
+]);
+
+/**
+ * Postgres writes the **entire failing row** into DETAIL for a CHECK or NOT NULL violation —
+ * every column of it, whatever that table happens to hold. Measured against Postgres 18:
+ *
+ *     detail: "Failing row contains (someone@example.com, 4242424242424242)."
+ *
+ * That is the one value-level rule in this file, and it is here rather than in a redaction pass
+ * because it is not a pattern over arbitrary text: it is one exact message form, and Postgres is
+ * the only thing that writes it. The unique-violation form — `Key (slug)=(demo) already exists.` —
+ * names only the key columns, which is the diagnostic this field is kept for, and survives.
+ */
+const PG_FAILING_ROW = "Failing row contains (";
+const OMITTED_ROW = "[row omitted: Postgres DETAIL for this error is the whole failing row]";
+
+function keptValue(key: string, value: unknown): unknown {
+  if ((key === "detail" || key === "details") && typeof value === "string") {
+    return value.startsWith(PG_FAILING_ROW) ? OMITTED_ROW : value;
+  }
+  return value;
+}
+
+/**
+ * A thrown value that is NOT an Error, narrowed to what a log line may print off it.
+ *
+ * The allow-list above is written against Errors, and until this the narrowing stopped there: an
+ * Error was filtered and whatever sat in its `cause` was copied whole. That gap is not theoretical
+ * here, it is this package's own doing — `errorBoundary` turns every non-Error throw into
+ * `new Error(toMessage(err), { cause: err })`, because Hono's `onError` never sees a non-Error and
+ * a PostgREST client rejects with plain objects. So in a Hono app the cause slot is precisely where
+ * a vendor's rejection object ends up, and a leak there reads as if the list had run.
+ *
+ * `cause` means "the error this one came from", so whatever sits in it is in the error slot and
+ * gets the same treatment. `name` and `message` come along because a rejection object usually
+ * carries them and a line with neither says nothing at all.
+ *
+ * Deliberate state it does NOT keep: context an app attaches on purpose. That belongs in the
+ * logger's `meta`, which is untouched — `cause` is not the place for it, and one incident of a
+ * vendor's request body in the log outweighs a field nobody put there deliberately.
+ */
+export function narrowErrorLike(value: object): Record<string, unknown> {
+  return narrow(value, new WeakSet<object>());
+}
+
+function narrow(value: object, seen: WeakSet<object>): Record<string, unknown> {
+  seen.add(value);
+  const out: Record<string, unknown> = {};
+  const { name, message, cause } = value as {
+    name?: unknown;
+    message?: unknown;
+    cause?: unknown;
+  };
+  if (typeof name === "string") out.name = name;
+  if (typeof message === "string") out.message = message;
+  for (const [k, v] of Object.entries(value)) {
+    if (KEPT_ERROR_FIELDS.has(k)) out[k] = keptValue(k, v);
+  }
+  if (cause !== undefined) out.cause = narrowCause(cause, seen);
+  return out;
+}
+
+/**
+ * An Error cause goes back unchanged, because `JSON.stringify` walks it into the replacer's own
+ * Error branch. Anything that is not an object is a string or a number, which is its own value.
+ */
+function narrowCause(cause: unknown, seen: WeakSet<object>): unknown {
+  if (cause instanceof Error || typeof cause !== "object" || cause === null) return cause;
+  // The recursion builds new objects, so the replacer's `seen` cannot see this chain: a rejection
+  // that holds itself would recurse until the stack ends, inside the one call that must never take
+  // the process down.
+  return seen.has(cause) ? "[Circular]" : narrow(cause, seen);
+}
+
+/**
+ * A `JSON.stringify` replacer that keeps log lines useful and crash-proof:
+ *
+ * - Errors serialize to a readable object. `message` and `stack` are non-enumerable, so a plain
+ *   `JSON.stringify(err)` is `{}` — which is how a logger ends up printing nothing about the
+ *   failure it was called to report. They are added explicitly, and the allow-listed extras ride
+ *   along beside them.
+ * - A nested `cause` is followed, and so is an `AggregateError`'s `errors`. Both are
+ *   non-enumerable, so both are invisible to the loop above; without this line "all attempts
+ *   failed" is the whole log entry. Each one goes back through this replacer, so the allow-list
+ *   covers the chain, not just the top — and a cause that is not an Error is narrowed here
+ *   instead, by {@link narrowErrorLike}, because the replacer's Error branch would never see it.
+ * - bigints stringify instead of throwing.
+ * - Circular references collapse to "[Circular]" instead of crashing the log call.
+ *
+ * Paired with callers passing the RAW error rather than `String(err)`, this is why a log line
+ * never reads "[object Object]".
+ *
+ * One ordering fact decides what this replacer would otherwise see: `JSON.stringify` calls a
+ * value's own `toJSON()` **before** the replacer, so an error class that defines one arrives here
+ * already turned into whatever that method returns — the stack and the cause gone, and the result
+ * usually shaped for the WIRE, because that is what an error's `toJSON()` is for. Seven backends
+ * on this stack define one, and `logger.error("x", { error: appErr })` wrote
+ * `{"error":{"error":{…}}}` in every one of them: double-nested, no stack, no cause, and
+ * invisible, because the line still looks like a log line.
+ *
+ * The original is still there. `JSON.stringify` calls the replacer with the HOLDER as `this`, and
+ * the holder's own property is the untouched value — so `this[key]` recovers the Error that
+ * `toJSON()` replaced. That is why this is a `function` and not an arrow.
+ *
+ * What a log line keeps off an Error is this file's decision, not the error's: an error class is
+ * free to define the body it sends a client, and the log still gets name, message, stack, cause
+ * and the allow-list.
+ *
+ * A new replacer per log line, because the `seen` set must not outlive one entry.
+ */
+export function errorReplacer(): (this: unknown, key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return function (key, value) {
+    const held =
+      typeof this === "object" && this !== null
+        ? (this as Record<string, unknown>)[key]
+        : undefined;
+    if (held instanceof Error) value = held;
+    if (typeof value === "bigint") return value.toString();
+    if (value instanceof Error) {
+      if (seen.has(value)) return "[Circular]";
+      seen.add(value);
+      const out: Record<string, unknown> = { name: value.name, message: value.message };
+      for (const [k, v] of Object.entries(value)) {
+        if (KEPT_ERROR_FIELDS.has(k)) out[k] = keptValue(k, v);
+      }
+      const { cause } = value;
+      if (cause !== undefined) out.cause = narrowCause(cause, seen);
+      if (value instanceof AggregateError) out.errors = value.errors;
+      if (value.stack) out.stack = value.stack;
+      return out;
+    }
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) return "[Circular]";
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+/** The keys an Error may contribute to a log line, beside `name`, `message`, `stack` and `cause`. */
+export const keptErrorFields: ReadonlySet<string> = KEPT_ERROR_FIELDS;

package/src/readme.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The README's examples, compiled and run.
+ *
+ * A snippet nobody executes rots quietly, and this one is the first thing an adopter copies.
+ * Every literal below is what the README prints beside the call.
+ */
+import { describe, expect, it } from "vitest";
+import { Hono } from "hono";
+import { createAppError, createErrorResponse, createLogger, ok, paginated } from "./index.ts";
+import {
+  assertEveryRouteGuarded,
+  errorBoundary,
+  errorHandler,
+  guard,
+  notFoundHandler,
+  requestLogger,
+  underAny,
+} from "./hono/index.ts";
+import type { RequestVariables } from "./hono/index.ts";
+
+type ErrorCode =
+  "VALIDATION_ERROR" | "UNAUTHORIZED" | "NOT_FOUND" | "RATE_LIMIT_EXCEEDED" | "INTERNAL_ERROR";
+type MessageKey = "serverErrors.notFound";
+
+const ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  RATE_LIMIT_EXCEEDED: 429,
+  INTERNAL_ERROR: 500,
+} as const satisfies Record<ErrorCode, number>;
+
+const appError = createAppError<typeof ERROR_STATUS, MessageKey>(ERROR_STATUS);
+
+const errors = {
+  notFound: (what = "Resource") => appError("NOT_FOUND", `${what} not found`),
+  rateLimit: (retryAfterSecs: number) =>
+    appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs }),
+};
+
+const errorResponse = createErrorResponse<ErrorCode, MessageKey>({
+  internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+  validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+});
+
+describe("the README", () => {
+  it("prints what ok() returns", () => {
+    expect(ok({ id: 1 })).toEqual({ status: 200, body: { data: { id: 1 } } });
+  });
+
+  it("prints what paginated() returns", () => {
+    const rows = [1, 2];
+    expect(paginated(rows, { total: 128, limit: 20, offset: 100 })).toEqual({
+      status: 200,
+      body: { data: rows, meta: { total: 128, limit: 20, offset: 100, hasMore: true } },
+    });
+  });
+
+  it("throws and answers the way the two snippets say", () => {
+    expect(errorResponse(errors.notFound("Workspace"))).toEqual({
+      status: 404,
+      body: { error: { code: "NOT_FOUND", message: "Workspace not found" } },
+      headers: {},
+      kind: "client",
+    });
+  });
+
+  it("puts a stated wait in the header and in details, from one value", () => {
+    const answer = errorResponse(errors.rateLimit(45));
+    expect(answer.headers["Retry-After"]).toBe("45");
+    expect(answer.body.error.details).toEqual({ retryAfterSecs: 45 });
+  });
+
+  it("logs the raw error and keeps the vendor's own input out of the line", async () => {
+    // The README says to pass the error itself, and says the allow-list covers the cause chain
+    // including a link that is not an Error. Both are one call here, because an adopter copies
+    // the line and gets both or neither.
+    const lines: string[] = [];
+    const logger = createLogger({ write: (line) => lines.push(line) });
+    const rejected = { message: "invalid signature", code: "PGRST301", payload: "the whole body" };
+
+    logger.error("charge failed", {
+      orderId: "ord_1",
+      error: new Error("invalid signature", { cause: rejected }),
+    });
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).not.toContain("the whole body");
+    const entry = JSON.parse(String(lines[0])) as { error: { cause: unknown; stack: string } };
+    expect(entry.error.cause).toEqual({ message: "invalid signature", code: "PGRST301" });
+    expect(entry.error.stack).toContain("Error: invalid signature");
+  });
+
+  it("mounts the four Hono pieces in the order the snippet mounts them", async () => {
+    // Mounted exactly as the README prints it, then made to throw a NON-Error — which is the
+    // reason the README calls errorBoundary not optional. Without it Hono never reaches onError
+    // and the request ends with no answer at all.
+    const logger = createLogger({ level: "silent" });
+    const app = new Hono<{ Variables: RequestVariables<ErrorCode> }>();
+    app.use(requestLogger({ logger }));
+    app.use(errorBoundary);
+    app.onError(errorHandler({ errorResponse, logger }));
+    app.notFound(notFoundHandler(errorResponse(errors.notFound("Route"))));
+    // A rejection with a plain object, which is the case the boundary exists for.
+    app.get("/boom", () => Promise.reject({ code: "PGRST301", payload: "the whole body" }));
+
+    const boom = await app.request("/boom");
+    const missing = await app.request("/nope");
+
+    expect(boom.status).toBe(500);
+    expect(await boom.text()).not.toContain("the whole body");
+    expect(boom.headers.get("X-Request-ID")).toMatch(/^[A-Za-z0-9._-]{1,64}$/);
+    expect(missing.status).toBe(404);
+    expect(await missing.json()).toEqual({
+      error: { code: "NOT_FOUND", message: "Route not found" },
+    });
+  });
+
+  it("fails the guard check on the route the README says it names", () => {
+    // The snippet's whole claim: the matcher is asked, so a `use` registered AFTER its route is
+    // reported even though the pattern list would look complete.
+    const requireUser = guard(async (_c, next) => next());
+    const app = new Hono();
+    app.get("/public/status", (c) => c.text("ok"));
+    app.get("/private/thing", (c) => c.text("secret"));
+    app.use("/private/*", requireUser); // too late: registered after the route it guards
+
+    expect(() => assertEveryRouteGuarded(app, { isPublic: underAny(["/public"]) })).toThrow(
+      /\/private\/thing/,
+    );
+  });
+});