@nwire/koa 0.10.0 → 0.11.0

package/README.md

@@ -17,10 +17,9 @@ import { z } from "zod";
 
 const app = createApp({ appName: "api" });
 
-app.wire(
-  post("/hello", { body: z.object({ name: z.string().min(1) }) }),
-  async (input) => ({ message: `Hello, ${input.name}!` }),
-);
+app.wire(post("/hello", { body: z.object({ name: z.string().min(1) }) }), async (input) => ({
+  message: `Hello, ${input.name}!`,
+}));
 
 await endpoint("api", { port: 3000 })
   .use(httpKoa({ prefix: "/api" }))
@@ -32,14 +31,14 @@ await endpoint("api", { port: 3000 })
 
 ```ts
 httpKoa({
-  port: 3000,                   // 0 = ephemeral; .port() returns the bound port after boot
+  port: 3000, // 0 = ephemeral; .port() returns the bound port after boot
   host: "0.0.0.0",
-  prefix: "/api",               // mounted on every wired route
-  helmet: true,                 // default-on; pass false to disable
-  cors: { origin: "*" },        // pass an options object or true; false to disable
+  prefix: "/api", // mounted on every wired route
+  helmet: true, // default-on; pass false to disable
+  cors: { origin: "*" }, // pass an options object or true; false to disable
   bodyParser: { jsonLimit: "1mb" },
-  middleware: [requireUser],    // adopter-wide Koa middleware run before every wire
-  logger: myLogger,             // defaults to ConsoleLogger
+  middleware: [requireUser], // adopter-wide Koa middleware run before every wire
+  logger: myLogger, // defaults to ConsoleLogger
 });
 ```
 
@@ -66,13 +65,10 @@ Two shapes are supported and route to the same dispatch:
 
 ```ts
 // Foundation HTTP — plain (input, ctx)
-app.wire(
-  post("/order", { body: OrderBody }),
-  async (input, ctx) => {
-    const repo = ctx.resolve<OrderRepo>("orders");
-    return repo.create(input);
-  },
-);
+app.wire(post("/order", { body: OrderBody }), async (input, ctx) => {
+  const repo = ctx.resolve<OrderRepo>("orders");
+  return repo.create(input);
+});
 
 // Forge HandlerDefinition — routed through runtime.execute
 const placeOrder = defineHandler(placeOrderAction, async (input, ctx) => {
@@ -89,13 +85,13 @@ take the direct path with a minimal ctx (`resolve`, `logger`, `koa`,
 
 ## Response shaping
 
-| Handler returns                                     | HTTP response                  |
-| --------------------------------------------------- | ------------------------------ |
-| `{ $kind: "response-instance", status, body }`      | `status`, JSON body            |
-| `{ $status, body }` (legacy envelope)               | `$status`, JSON body           |
-| anything else                                       | `200`, JSON serialized verbatim |
-| validation throws                                   | `400`, structured error JSON   |
-| handler throws `defineError`-shaped                 | `error.status`, structured JSON |
+| Handler returns                                | HTTP response                   |
+| ---------------------------------------------- | ------------------------------- |
+| `{ $kind: "response-instance", status, body }` | `status`, JSON body             |
+| `{ $status, body }` (legacy envelope)          | `$status`, JSON body            |
+| anything else                                  | `200`, JSON serialized verbatim |
+| validation throws                              | `400`, structured error JSON    |
+| handler throws `defineError`-shaped            | `error.status`, structured JSON |
 
 ## Testing
 

package/dist/http-koa.d.ts

@@ -16,20 +16,15 @@
  * — the handler returns a value that becomes ctx.body; status defaults
  * to 200; { $status, body } objects unwrap.
  *
- * 0.10 first-pass scope:
+ * Scope:
  *   - helmet + cors + body parser layered when configured
  *   - per-wire handler dispatch via Koa router
  *   - per-request scoped container (parent = wire's source app)
  *   - dispatched as Adapter so endpoint().use(httpKoa()).mount(app).run()
  *     works end-to-end
- *
- * Deferred (lands in 0.10.x):
- *   - OpenAPI document + /docs serving
- *   - Scalar docs UI
- *   - Inspect endpoints under /_nwire/*
- *   - Per-route middleware (RouteBinding.middleware)
- *   - Per-request envelope scope (forge integration)
- *   - fromKoaApp / fromKoaMiddleware / fromKoa auto-wrapper
+ *   - inspect surface at /_nwire/* (opt-in via `inspect` config or
+ *     the NWIRE_INSPECT env var) — manifest, dispatch, event/telemetry
+ *     ring buffers + SSE
  */
 import type { Adapter } from "@nwire/endpoint";
 import { type Logger } from "@nwire/logger";
@@ -54,6 +49,29 @@ export interface HttpKoaConfig {
      */
     readonly middleware?: readonly Koa.Middleware[];
     readonly logger?: Logger;
+    /**
+     * Correlation-id middleware. Default `true`. When enabled, every
+     * request gets `x-correlation-id`: if the client sent one (via
+     * `x-correlation-id` or `x-request-id`) it's reused; otherwise a fresh
+     * UUID is generated. The value lands on `envelope.correlationId` and
+     * is echoed back as a response header so distributed traces stitch.
+     *
+     * Set to `false` to opt out (e.g. if you have a custom request-id
+     * middleware running upstream).
+     */
+    readonly reqId?: boolean;
+    /**
+     * Tenant resolver. The dev/test default reads `x-tenant` from the
+     * request header — convenient for local multi-tenancy. Production
+     * MUST pass a resolver that derives tenancy from a verified source
+     * (a JWT claim, a session, a host header bound to a tenant config)
+     * — raw `x-tenant` from clients is trivially spoofable.
+     *
+     * When `NODE_ENV === "production"` and no resolver is provided,
+     * `envelope.tenant` is left undefined so the raw header can't be
+     * trusted.
+     */
+    readonly tenantResolver?: (kctx: Koa.ParameterizedContext) => string | undefined;
     /**
      * OpenAPI 3.1 doc — three forms of input:
      *   - `auto: true` — generate the spec by walking the adopter's wires;

package/dist/http-koa.js

@@ -16,22 +16,18 @@
  * — the handler returns a value that becomes ctx.body; status defaults
  * to 200; { $status, body } objects unwrap.
  *
- * 0.10 first-pass scope:
+ * Scope:
  *   - helmet + cors + body parser layered when configured
  *   - per-wire handler dispatch via Koa router
  *   - per-request scoped container (parent = wire's source app)
  *   - dispatched as Adapter so endpoint().use(httpKoa()).mount(app).run()
  *     works end-to-end
- *
- * Deferred (lands in 0.10.x):
- *   - OpenAPI document + /docs serving
- *   - Scalar docs UI
- *   - Inspect endpoints under /_nwire/*
- *   - Per-route middleware (RouteBinding.middleware)
- *   - Per-request envelope scope (forge integration)
- *   - fromKoaApp / fromKoaMiddleware / fromKoa auto-wrapper
+ *   - inspect surface at /_nwire/* (opt-in via `inspect` config or
+ *     the NWIRE_INSPECT env var) — manifest, dispatch, event/telemetry
+ *     ring buffers + SSE
  */
 import http from "node:http";
+import { randomUUID } from "node:crypto";
 import { dummyContainer } from "@nwire/container";
 import { ConsoleLogger } from "@nwire/logger";
 import Koa from "koa";
@@ -65,24 +61,54 @@ export function httpKoa(config = {}) {
         async boot(ctx) {
             const koa = new Koa();
             koaInstance = koa;
+            const isProd = process.env.NODE_ENV === "production";
             // Top-level error mapper — catches throws from middleware and
             // unmatched routes. Renders defineError-shaped values with their
-            // {code, status, summary} envelope; otherwise opaque 500.
+            // {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.
             koa.use(async (kctx, next) => {
                 try {
                     await next();
                 }
                 catch (err) {
                     const e = err;
-                    kctx.status = typeof e.status === "number" ? e.status : 500;
-                    kctx.body = {
-                        error: {
-                            code: e.code ?? "internal_error",
-                            summary: e.summary ?? e.message ?? "Internal error",
-                        },
-                    };
+                    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);
+                        kctx.body = {
+                            error: { code: "internal_error", summary: "Internal error" },
+                        };
+                    }
+                    else {
+                        kctx.body = {
+                            error: {
+                                code: e.code ?? "internal_error",
+                                summary: e.summary ?? e.message ?? "Internal error",
+                            },
+                        };
+                    }
                 }
             });
+            // Correlation-id: opt-out (default on). Reuses an inbound
+            // `x-correlation-id` / `x-request-id`; mints a UUID otherwise.
+            // Stamps `kctx.state.correlationId` for downstream consumers and
+            // echoes the response header so traces stitch end-to-end.
+            if (config.reqId !== false) {
+                koa.use(async (kctx, next) => {
+                    const incoming = kctx.request.headers["x-correlation-id"] ??
+                        kctx.request.headers["x-request-id"];
+                    const correlationId = incoming && incoming.length > 0 ? incoming : randomUUID();
+                    kctx.state.correlationId = correlationId;
+                    kctx.set("x-correlation-id", correlationId);
+                    await next();
+                });
+            }
             if (config.helmet !== false) {
                 koa.use(helmet());
             }
@@ -125,9 +151,27 @@ export function httpKoa(config = {}) {
             }
             if (docsConfig !== null) {
                 koa.use(async (kctx, next) => {
-                    if (kctx.method !== "GET" || kctx.path !== docsPath)
+                    if (kctx.path !== docsPath)
+                        return next();
+                    if (kctx.method !== "GET" && kctx.method !== "HEAD")
                         return next();
+                    // Scalar's bundle loads from cdn.jsdelivr.net; relax CSP just
+                    // for this route so the docs render in a browser. Other routes
+                    // keep helmet's strict defaults.
+                    kctx.set("Content-Security-Policy", "default-src 'self'; " +
+                        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; " +
+                        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; " +
+                        "font-src 'self' https://fonts.gstatic.com data:; " +
+                        "img-src 'self' data: https:; " +
+                        "connect-src 'self'");
                     kctx.type = "text/html";
+                    if (kctx.method === "HEAD") {
+                        // Force 200 + empty body. Koa otherwise rewrites the status
+                        // when body is null/undefined.
+                        kctx.status = 200;
+                        kctx.body = "";
+                        return;
+                    }
                     kctx.body = `<!doctype html>
 <html>
   <head>
@@ -145,8 +189,16 @@ export function httpKoa(config = {}) {
             // /_nwire/* introspection — mounted before adopter-wide auth so
             // Studio can read manifest/wires/runtime without an admin token.
             // Production consumers gate via inspect.middleware.
-            if (config.inspect) {
-                const inspectConfig = config.inspect === true ? {} : config.inspect;
+            //
+            // Auto-on when `NWIRE_INSPECT=1` is in the environment: Studio
+            // sets this when it spawns a dev process, so the live proxy "just
+            // works" without the app's main.ts having to opt in. Explicit
+            // `inspect:` config still wins — pass `inspect: false` to keep
+            // production deployments clean even if the env var leaks in.
+            const inspectEnvOn = process.env.NWIRE_INSPECT === "1" || process.env.NWIRE_INSPECT === "true";
+            const inspectEnabled = config.inspect ?? inspectEnvOn;
+            if (inspectEnabled) {
+                const inspectConfig = inspectEnabled === true ? {} : inspectEnabled;
                 const { mountInspect } = await import("./inspect.js");
                 // Find a representative source app — we mount inspect against the
                 // first wire's owning app; the wire collection is what we report.
@@ -163,9 +215,7 @@ export function httpKoa(config = {}) {
             for (const mw of config.middleware ?? []) {
                 koa.use(mw);
             }
-            const router = config.prefix
-                ? new KoaRouter({ prefix: config.prefix })
-                : new KoaRouter();
+            const router = config.prefix ? new KoaRouter({ prefix: config.prefix }) : new KoaRouter();
             for (const wire of ctx.wires) {
                 if (!isHttpBinding(wire.binding))
                     continue;
@@ -213,14 +263,25 @@ export function httpKoa(config = {}) {
                         logger,
                         koa: kctx,
                     };
-                    // Per-request envelope derived from request headers — userId set
-                    // by adopter middleware lands on it; tenant flows from a header
-                    // for simple multi-tenancy; correlationId / causationId come
-                    // from upstream callers so distributed traces stitch in.
+                    // Per-request envelope. correlationId is set by the req-id
+                    // middleware above (or whatever the upstream caller sent).
+                    // tenant goes through `tenantResolver` if provided; the dev/test
+                    // default reads `x-tenant`, but in production we refuse to trust
+                    // the raw header — a resolver must derive tenancy from a verified
+                    // source (a JWT claim, a session, a host binding).
+                    const resolveTenant = config.tenantResolver ??
+                        ((kc) => isProd
+                            ? undefined
+                            : (kc.request.headers["x-tenant"] ?? undefined));
                     const envelopePartial = {
-                        tenant: kctx.request.headers["x-tenant"] ?? undefined,
+                        tenant: resolveTenant(kctx),
                         userId: kctx.state.userId ?? undefined,
-                        correlationId: kctx.request.headers["x-correlation-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
+                        // the transport.
+                        user: kctx.state.user ?? undefined,
+                        correlationId: kctx.state.correlationId,
                         causationId: kctx.request.headers["x-causation-id"] ?? undefined,
                     };
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -248,16 +309,28 @@ export function httpKoa(config = {}) {
                         }
                     }
                     catch (err) {
-                        // Generic error envelope; downstream phases hook in nwire-error
-                        // mapping + sanitised production responses.
+                        // 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.
                         const e = err;
+                        const isNwireError = e?.$kind === "error";
                         kctx.status = typeof e.status === "number" ? e.status : 500;
-                        kctx.body = {
-                            error: {
-                                code: e.code ?? "internal_error",
-                                summary: e.summary ?? e.message ?? "Internal error",
-                            },
-                        };
+                        if (!isNwireError && isProd) {
+                            logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
+                            kctx.body = {
+                                error: { code: "internal_error", summary: "Internal error" },
+                            };
+                        }
+                        else {
+                            kctx.body = {
+                                error: {
+                                    code: e.code ?? "internal_error",
+                                    summary: e.summary ?? e.message ?? "Internal error",
+                                },
+                            };
+                        }
                         return;
                     }
                     // Response shaping:

package/dist/inspect.js

@@ -30,16 +30,117 @@ function summarizeWire(wire) {
         source: b.source,
     };
 }
+/**
+ * Studio's Trace page expects a flatter shape with `capturedAt` and a
+ * stable `seq` per stream. Telemetry records hold the same data under
+ * `event.{eventName,payload}` + `ts`, so we project at the API boundary
+ * rather than reshape every consumer of the ring buffer.
+ */
+function toBufferedEvent(rec, seq) {
+    return {
+        seq,
+        eventName: rec.event?.eventName,
+        payload: rec.event?.payload,
+        envelope: rec.envelope ?? {},
+        source: rec.source ?? "in-process",
+        appName: rec.appName ?? "",
+        capturedAt: rec.ts ?? rec.envelope?.timestamp ?? new Date().toISOString(),
+    };
+}
+class RingBuffer {
+    cap;
+    items = [];
+    constructor(cap) {
+        this.cap = cap;
+    }
+    push(rec) {
+        this.items.push(rec);
+        if (this.items.length > this.cap)
+            this.items.shift();
+    }
+    recent(n) {
+        const limit = n ?? this.items.length;
+        return this.items.slice(-limit);
+    }
+}
+function attachStreams(opts) {
+    const events = new RingBuffer(500);
+    const telemetry = new RingBuffer(500);
+    const listeners = new Set();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rt = opts.app?.runtime;
+    if (typeof rt?.onTelemetry === "function") {
+        rt.onTelemetry((rec) => {
+            telemetry.push(rec);
+            if (rec.kind === "event.published" || rec.kind === "event.deduped") {
+                events.push(rec);
+            }
+            for (const fn of listeners) {
+                try {
+                    fn(rec);
+                }
+                catch {
+                    // Listener crashed; drop without taking the runtime with it.
+                }
+            }
+        });
+    }
+    return {
+        events,
+        telemetry,
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+    };
+}
+const streamsByMount = new WeakMap();
+function streamsFor(opts) {
+    let s = streamsByMount.get(opts);
+    if (!s) {
+        s = attachStreams(opts);
+        streamsByMount.set(opts, s);
+    }
+    return s;
+}
 export function mountInspect(koa, opts) {
     const prefix = opts.config.prefix ?? "/_nwire";
+    const chain = opts.config.middleware ?? [];
+    const isProd = process.env.NODE_ENV === "production";
+    // Eagerly attach the telemetry tap on the App's runtime so we don't
+    // miss records emitted before the first /_nwire/* request.
+    streamsFor(opts);
+    // Production guardrail: `/dispatch` is remote-handler invocation. If the
+    // caller didn't gate it with adopter middleware, refuse to expose it
+    // under NODE_ENV=production. The read-only `/manifest`, `/wires`,
+    // `/runtime`, `/actors`, `/queries` routes still serve (they only leak
+    // metadata) but POST `/dispatch` returns 403. Dev/test still mounts
+    // freely so Studio + tests work without extra setup.
+    const allowDispatch = !isProd || chain.length > 0;
+    if (isProd && !allowDispatch) {
+        // eslint-disable-next-line no-console
+        console.warn(`[http-koa] /_nwire/dispatch is disabled under NODE_ENV=production ` +
+            `because no inspect.middleware guard was configured. Pass ` +
+            `httpKoa({ inspect: { middleware: [requireAdmin] } }) to re-enable.`);
+    }
     const handle = async (kctx, next) => {
         if (!kctx.path.startsWith(prefix + "/"))
             return next();
+        const sub = kctx.path.slice(prefix.length);
+        if (kctx.method === "POST" && sub === "/dispatch" && !allowDispatch) {
+            kctx.status = 403;
+            kctx.body = {
+                error: {
+                    code: "dispatch_disabled",
+                    summary: "Inspect dispatch is disabled under NODE_ENV=production without explicit middleware guard.",
+                },
+            };
+            return;
+        }
         // Adopter-wide middleware first (if any). We model these as a chain;
         // Koa doesn't expose runtime chain composition for arbitrary inputs,
         // so we fold them with a manual chain.
         let i = 0;
-        const chain = opts.config.middleware ?? [];
         const runNext = async () => {
             const mw = chain[i++];
             if (mw)
@@ -76,13 +177,66 @@ async function dispatchInspect(kctx, opts) {
         kctx.body = JSON.stringify({
             appName: opts.app?.appName ?? null,
             hasRuntime: typeof rt === "object" && rt !== null,
-            lifecycle: rt?.lifecycle ?? "unknown",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            lifecycle: opts.app?.state ?? rt?.lifecycle ?? "unknown",
             handlers: typeof rt?.listHandlers === "function"
-                ? rt.listHandlers().map((h) => typeof h === "string" ? h : (h?.name ?? null)).filter(Boolean)
+                ? rt.listHandlers()
+                    .map((h) => (typeof h === "string" ? h : (h?.name ?? null)))
+                    .filter(Boolean)
                 : [],
         });
         return;
     }
+    if (kctx.method === "GET" && (sub === "/events/recent" || sub === "/telemetry/recent")) {
+        const streams = streamsFor(opts);
+        const limit = Number(kctx.query.limit ?? "200") || 200;
+        const buf = sub === "/events/recent" ? streams.events : streams.telemetry;
+        const records = buf.recent(limit);
+        kctx.type = "application/json";
+        kctx.body = JSON.stringify(sub === "/events/recent" ? records.map((rec, i) => toBufferedEvent(rec, i)) : records);
+        return;
+    }
+    if (kctx.method === "GET" && (sub === "/events/stream" || sub === "/telemetry/stream")) {
+        const streams = streamsFor(opts);
+        const onlyEvents = sub === "/events/stream";
+        kctx.respond = false;
+        const res = kctx.res;
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+        // Backfill from the ring buffer.
+        const backfill = onlyEvents ? streams.events.recent(50) : streams.telemetry.recent(50);
+        let seq = 0;
+        for (const rec of backfill) {
+            const payload = onlyEvents ? toBufferedEvent(rec, seq++) : rec;
+            res.write(`data: ${JSON.stringify(payload)}\n\n`);
+        }
+        const unsub = streams.subscribe((rec) => {
+            if (onlyEvents && rec.kind !== "event.published" && rec.kind !== "event.deduped")
+                return;
+            try {
+                const payload = onlyEvents ? toBufferedEvent(rec, seq++) : rec;
+                res.write(`data: ${JSON.stringify(payload)}\n\n`);
+            }
+            catch {
+                // socket gone
+            }
+        });
+        const keepalive = setInterval(() => {
+            try {
+                res.write(": keepalive\n\n");
+            }
+            catch {
+                // socket gone
+            }
+        }, 25_000);
+        kctx.req.on("close", () => {
+            unsub();
+            clearInterval(keepalive);
+        });
+        return;
+    }
     if (kctx.method === "GET" && sub.startsWith("/actors/")) {
         // Per-type actor listing requires an ActorStore binding. We try to
         // resolve it from the container; if absent, return 501.

package/dist/openapi.js

@@ -82,9 +82,7 @@ export async function generateOpenApi(wires, options = {}) {
             request: {
                 ...(b.params ? { params: b.params } : {}),
                 ...(b.query ? { query: b.query } : {}),
-                ...(b.body
-                    ? { body: { content: { "application/json": { schema: b.body } } } }
-                    : {}),
+                ...(b.body ? { body: { content: { "application/json": { schema: b.body } } } } : {}),
             },
             responses,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/koa",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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/endpoint": "0.10.0",
-    "@nwire/wires": "0.10.0",
-    "@nwire/logger": "0.10.0",
-    "@nwire/container": "0.10.0"
+    "@nwire/container": "0.11.0",
+    "@nwire/endpoint": "0.11.0",
+    "@nwire/logger": "0.11.0",
+    "@nwire/wires": "0.11.0"
   },
   "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.10.0",
-    "@nwire/handler": "0.10.0"
+    "@nwire/handler": "0.11.0",
+    "@nwire/app": "0.11.0"
   },
   "peerDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.0.0"