@nwire/koa 0.11.1 → 0.12.1

package/dist/http-koa.d.ts

@@ -60,6 +60,20 @@ export interface HttpKoaConfig {
      * middleware running upstream).
      */
     readonly reqId?: boolean;
+    /**
+     * Echo raw thrown `Error.message` to the client for non-typed errors.
+     *
+     * Default `false` — a generic `throw new Error("…")` returns an opaque
+     * `{ code: "internal_error", summary: "Internal error" }` and the real
+     * message is logged server-side only. This is fail-safe: driver errors,
+     * connection strings, and PII attached to a stray throw never reach the
+     * client, in any environment.
+     *
+     * Set `true` in local dev to surface the message for debugging. Typed
+     * `defineError` values always render their own `{ code, summary }`
+     * regardless — those are author-defined and safe to expose.
+     */
+    readonly exposeErrors?: boolean;
     /**
      * Tenant resolver. The dev/test default reads `x-tenant` from the
      * request header — convenient for local multi-tenancy. Production

package/dist/http-koa.js

@@ -35,6 +35,24 @@ import bodyParser from "koa-bodyparser";
 import cors from "@koa/cors";
 import helmet from "koa-helmet";
 import KoaRouter from "@koa/router";
+/** Zod throws a `ZodError` (name + `issues[]`) on a failed `.parse()`. */
+function isZodError(e) {
+    return (typeof e === "object" &&
+        e !== null &&
+        e.name === "ZodError" &&
+        Array.isArray(e.issues));
+}
+/**
+ * A human-readable summary of the first validation issue. Safe to expose:
+ * it describes the caller's own input, not internal state.
+ */
+function zodSummary(e) {
+    const first = e.issues[0];
+    if (!first)
+        return "validation failed";
+    const path = (first.path ?? []).join(".") || "(body)";
+    return `${path}: ${first.message}`;
+}
 function isHttpBinding(b) {
     return (typeof b === "object" &&
         b !== null &&
@@ -62,12 +80,14 @@ export function httpKoa(config = {}) {
             const koa = new Koa();
             koaInstance = koa;
             const isProd = process.env.NODE_ENV === "production";
+            const exposeErrors = config.exposeErrors === true;
             // Top-level error mapper — catches throws from middleware and
-            // unmatched routes. Renders defineError-shaped values with their
-            // {code, status, summary} envelope; in production, generic
-            // (non-NwireError) throws return opaque "internal_error" so a
-            // stray `throw new Error("DB password X")` cannot leak the
-            // message to clients. The real error is always logged.
+            // unmatched routes. Typed `defineError` values render their own
+            // {code, status, summary}. Generic (non-NwireError) throws return an
+            // opaque "internal_error" by default so a stray
+            // `throw new Error("DB password X")` cannot leak the message to
+            // clients — in any environment. `exposeErrors: true` (dev) echoes
+            // the message. The real error is always logged server-side.
             koa.use(async (kctx, next) => {
                 try {
                     await next();
@@ -75,21 +95,27 @@ export function httpKoa(config = {}) {
                 catch (err) {
                     const e = err;
                     const isNwireError = e?.$kind === "error";
-                    const status = typeof e.status === "number" ? e.status : 500;
-                    kctx.status = status;
-                    if (!isNwireError && isProd) {
-                        // Server-side: log the full error so SRE can see it. Client:
-                        // opaque body — no error.message leak.
-                        logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
+                    if (isZodError(err)) {
+                        // A schema `.parse()` that escaped the per-route catch (e.g. an
+                        // action's own input schema). Validation failures are the
+                        // caller's fault → 400 with a readable summary, never an opaque
+                        // 500. The message is about their input, so it's safe to expose.
+                        kctx.status = 400;
+                        kctx.body = { error: { code: "validation_failed", summary: zodSummary(err) } };
+                        return;
+                    }
+                    kctx.status = typeof e.status === "number" ? e.status : 500;
+                    if (isNwireError) {
                         kctx.body = {
-                            error: { code: "internal_error", summary: "Internal error" },
+                            error: { code: e.code ?? "internal_error", summary: e.summary ?? "Internal error" },
                         };
                     }
                     else {
+                        logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
                         kctx.body = {
                             error: {
-                                code: e.code ?? "internal_error",
-                                summary: e.summary ?? e.message ?? "Internal error",
+                                code: "internal_error",
+                                summary: exposeErrors ? (e.message ?? "Internal error") : "Internal error",
                             },
                         };
                     }
@@ -250,7 +276,7 @@ export function httpKoa(config = {}) {
                         kctx.body = {
                             error: {
                                 code: "validation_failed",
-                                summary: err.message,
+                                summary: isZodError(err) ? zodSummary(err) : err.message,
                             },
                         };
                         return;
@@ -275,7 +301,12 @@ export function httpKoa(config = {}) {
                             : (kc.request.headers["x-tenant"] ?? undefined));
                     const envelopePartial = {
                         tenant: resolveTenant(kctx),
-                        userId: kctx.state.userId ?? undefined,
+                        // Prefer an explicit `state.userId`, but fall back to the
+                        // user object's id so handlers reading `envelope.userId` work
+                        // whenever auth middleware populated `state.user`.
+                        userId: kctx.state.userId ??
+                            kctx.state.user?.id ??
+                            undefined,
                         // Pass the full user object through when adopter auth middleware
                         // populated it. Without this, transport-agnostic RBAC has to
                         // reach into `ctx.koa.state.user` and couples the handler to
@@ -309,25 +340,26 @@ export function httpKoa(config = {}) {
                         }
                     }
                     catch (err) {
-                        // Generic error envelope. NwireError-shaped values (defineError)
-                        // surface their {code, status, summary}. Other throws — under
-                        // NODE_ENV=production — return opaque "internal_error" so a
-                        // stray `throw new Error("DB password X")` cannot leak the
-                        // message to clients. The real error is always logged.
+                        // Generic error envelope. Typed `defineError` values surface
+                        // their {code, status, summary}. Other throws return an opaque
+                        // "internal_error" by default so a stray
+                        // `throw new Error("DB password X")` cannot leak the message to
+                        // clients — in any environment. `exposeErrors: true` (dev)
+                        // echoes the message. The real error is always logged.
                         const e = err;
                         const isNwireError = e?.$kind === "error";
                         kctx.status = typeof e.status === "number" ? e.status : 500;
-                        if (!isNwireError && isProd) {
-                            logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
+                        if (isNwireError) {
                             kctx.body = {
-                                error: { code: "internal_error", summary: "Internal error" },
+                                error: { code: e.code ?? "internal_error", summary: e.summary ?? "Internal error" },
                             };
                         }
                         else {
+                            logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
                             kctx.body = {
                                 error: {
-                                    code: e.code ?? "internal_error",
-                                    summary: e.summary ?? e.message ?? "Internal error",
+                                    code: "internal_error",
+                                    summary: exposeErrors ? (e.message ?? "Internal error") : "Internal error",
                                 },
                             };
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/koa",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Nwire — Koa-backed HTTP adopter. Consumes wires from @nwire/wires/http and serves them as Koa routes under endpoint lifecycle.",
   "keywords": [
     "adopter",
@@ -33,10 +33,10 @@
     "koa-bodyparser": "^4.4.1",
     "koa-helmet": "^8.0.1",
     "zod": "^4.0.0",
-    "@nwire/container": "0.11.1",
-    "@nwire/endpoint": "0.11.1",
-    "@nwire/logger": "0.11.1",
-    "@nwire/wires": "0.11.1"
+    "@nwire/endpoint": "0.12.1",
+    "@nwire/wires": "0.12.1",
+    "@nwire/logger": "0.12.1",
+    "@nwire/container": "0.12.1"
   },
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.0.0",
@@ -47,8 +47,8 @@
     "@types/node": "^22.19.9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
-    "@nwire/app": "0.11.1",
-    "@nwire/handler": "0.11.1"
+    "@nwire/app": "0.12.1",
+    "@nwire/handler": "0.12.1"
   },
   "peerDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.0.0"