stitchkit 0.110.5 → 0.110.6

package/CHANGELOG.md

@@ -15,6 +15,17 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.110.6] - 2026-10-15
+
+### Added
+
+- `stitchkit/server`: `createServer({ proxyOrigin: { trustedPeer } })` restores the external HTTP/HTTPS scheme from a single trusted ingress before fetch composition and routing. It validates the real TCP peer and one `X-Forwarded-Proto`, rejects competing URL headers, preserves wire Host/ports and native cancellation, peer lookup and WebSocket upgrade. `trustProxy` remains client-IP-only. The server surface grows by one configuration type, `ProxyOriginConfig`, owned by this entrypoint so the trust decision is explicit and independently testable (I8, I9, I12).
+
+### Fixed
+
+- `stitchkit/process`: bounded process-group settlement observations remain readable through nested cleanup errors in Node CI, including up to 16 actual states, the group id, sample count and elapsed time. Observation failures retain their original cause. Cleanup deadlines and the definition of a live process are unchanged; these diagnostics do not claim to repair a historical native termination failure.
+- `stitchkit/process`: stopping a process group repeats `SIGKILL` for members still confirmed alive within the original cleanup deadline. Fresh kernel absence ends further signals; dead-only, invalid and failed process observations never trigger a blind re-signal.
+
 ## [0.110.5] - 2026-10-15
 
 ### Added

package/dist/agent-runtime/branch-observations.d.ts

@@ -25,20 +25,8 @@ export declare function branchObservation(ids: BranchIdentities, kind: string, r
     delayMs?: number | undefined;
     reason?: string | undefined;
 } | {
-    effectName: string;
-    phase: "intent";
-    runId: string;
-    id?: string | undefined;
-} | {
-    effectName: string;
-    phase: "accepted";
+    stepName: string;
     encoded: string;
-    via: "reconcile" | "run";
-    runId: string;
-    id?: string | undefined;
-} | {
-    effectName: string;
-    phase: "uncertain";
     runId: string;
     id?: string | undefined;
 } | {
@@ -53,15 +41,27 @@ export declare function branchObservation(ids: BranchIdentities, kind: string, r
     id: string;
     runId: string;
 } | {
-    stepName: string;
+    event: string;
+    id: string;
     encoded: string;
     runId: string;
+} | {
+    effectName: string;
+    phase: "intent";
+    runId: string;
     id?: string | undefined;
 } | {
-    event: string;
-    id: string;
+    effectName: string;
+    phase: "accepted";
     encoded: string;
+    via: "reconcile" | "run";
+    runId: string;
+    id?: string | undefined;
+} | {
+    effectName: string;
+    phase: "uncertain";
     runId: string;
+    id?: string | undefined;
 } | {
     bytes: number;
     sha256?: string | undefined;

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -6,10 +6,10 @@ import {
   AgentCodingToolAuthorizationSchema2,
   AgentCodingToolPathAuthorizationSchema2,
   createAgentCodingTools2
-} from "../../index-bm180f2d.js";
+} from "../../index-ey15wx6j.js";
 import"../../index-2kbysk9s.js";
 import"../../index-84bf5spd.js";
-import"../../index-e1sjcjfy.js";
+import"../../index-7r4knwf8.js";
 import"../../index-zrtrjkbf.js";
 import"../../index-636mggad.js";
 export {

package/dist/entrypoints/agent-runtime/sandbox.js

@@ -3,7 +3,7 @@ import {
   missingSandboxRestrictions2,
   codingRefusal,
   createAgentCodingTools2
-} from "../../index-bm180f2d.js";
+} from "../../index-ey15wx6j.js";
 import"../../index-ct75c3at.js";
 import"../../index-q6crhe1n.js";
 import"../../index-fynr93w4.js";
@@ -17,7 +17,7 @@ import {
   nativeCommandOwner,
   terminateOwnedGroup,
   startNativeCommand
-} from "../../index-e1sjcjfy.js";
+} from "../../index-7r4knwf8.js";
 import"../../index-zrtrjkbf.js";
 import {
   MAX_TIMER_MS

package/dist/entrypoints/agent-runtime/sqlite/bun.js

@@ -1,20 +1,20 @@
 import"../../../index-jna0ejsa.js";
-import"../../../index-mpg1t7nv.js";
+import"../../../index-0z3kfphz.js";
 import"../../../index-8kzct1d6.js";
 import {
   initializeAgentRuntimeSqlite2,
   createSqliteAgentRuntimeStore2
-} from "../../../index-5pbtbce0.js";
+} from "../../../index-7c957abz.js";
 import"../../../index-kqnd6a85.js";
 import"../../../index-5w6t91ze.js";
-import"../../../index-bm180f2d.js";
+import"../../../index-ey15wx6j.js";
 import"../../../index-ct75c3at.js";
 import"../../../index-q6crhe1n.js";
 import"../../../index-fynr93w4.js";
 import"../../../index-2kbysk9s.js";
 import"../../../index-84bf5spd.js";
+import"../../../index-7r4knwf8.js";
 import"../../../index-snef22zr.js";
-import"../../../index-e1sjcjfy.js";
 import"../../../index-zrtrjkbf.js";
 import"../../../index-636mggad.js";
 

package/dist/entrypoints/agent-runtime/sqlite/node.js

@@ -1,20 +1,20 @@
 import"../../../index-jna0ejsa.js";
-import"../../../index-mpg1t7nv.js";
+import"../../../index-0z3kfphz.js";
 import"../../../index-8kzct1d6.js";
 import {
   initializeAgentRuntimeSqlite2,
   createSqliteAgentRuntimeStore2
-} from "../../../index-5pbtbce0.js";
+} from "../../../index-7c957abz.js";
 import"../../../index-kqnd6a85.js";
 import"../../../index-5w6t91ze.js";
-import"../../../index-bm180f2d.js";
+import"../../../index-ey15wx6j.js";
 import"../../../index-ct75c3at.js";
 import"../../../index-q6crhe1n.js";
 import"../../../index-fynr93w4.js";
 import"../../../index-2kbysk9s.js";
 import"../../../index-84bf5spd.js";
+import"../../../index-7r4knwf8.js";
 import"../../../index-snef22zr.js";
-import"../../../index-e1sjcjfy.js";
 import"../../../index-zrtrjkbf.js";
 import"../../../index-636mggad.js";
 

package/dist/entrypoints/agent-runtime/testing.js

@@ -10,18 +10,18 @@ import {
   advanceToolChronology
 } from "../../index-jna0ejsa.js";
 import"../../index-5w6t91ze.js";
-import"../../index-bm180f2d.js";
-import"../../index-mpg1t7nv.js";
+import"../../index-ey15wx6j.js";
+import"../../index-0z3kfphz.js";
 import"../../index-ct75c3at.js";
 import"../../index-q6crhe1n.js";
 import"../../index-fynr93w4.js";
 import"../../index-2kbysk9s.js";
 import"../../index-84bf5spd.js";
+import"../../index-7r4knwf8.js";
 import"../../index-snef22zr.js";
 import {
   createMemoryAgentRuntimeStore2
-} from "../../index-9ket8wzx.js";
-import"../../index-e1sjcjfy.js";
+} from "../../index-mnk5vgdr.js";
 import"../../index-zrtrjkbf.js";
 import {
   assertPositiveSafeInteger

package/dist/entrypoints/agent-runtime.js

@@ -5,7 +5,7 @@ import {
   missingSandboxRestrictions2,
   recordAgentSandboxProbe2,
   refuseUnknownSpillReference
-} from "../index-bm180f2d.js";
+} from "../index-ey15wx6j.js";
 import {
   AgentRecordIdSchema2,
   AgentRecordVersionSchema2,
@@ -58,7 +58,7 @@ import {
   AgentHistoryMutationSchema2,
   ACTIVE_AGENT_RUN_STATES2,
   createAgentRuntimeStore2
-} from "../index-mpg1t7nv.js";
+} from "../index-0z3kfphz.js";
 import {
   AgentStoreEventKindSchema2,
   AgentStoreEventEnvelopeSchema2,
@@ -188,13 +188,13 @@ import {
 import"../index-56yx8dxp.js";
 import"../index-2kbysk9s.js";
 import"../index-84bf5spd.js";
+import"../index-7r4knwf8.js";
 import {
   createMemoryAgentRuntimeStore2
-} from "../index-9ket8wzx.js";
+} from "../index-mnk5vgdr.js";
 import {
   createAgentRuntimeEventSink2
 } from "../index-616xh7f2.js";
-import"../index-e1sjcjfy.js";
 import"../index-zrtrjkbf.js";
 import {
   MAX_TIMER_MS

package/dist/entrypoints/process.js

@@ -9,7 +9,7 @@ import {
 } from "../index-84bf5spd.js";
 import {
   startNativeCommand
-} from "../index-e1sjcjfy.js";
+} from "../index-7r4knwf8.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;

package/dist/entrypoints/server.d.ts

@@ -23,6 +23,7 @@ export { createTrustFence, isLoopbackAddress, type TrustFence, type TrustFenceCo
 export { type MultipartLifecycle, type MultipartResult, parseMultipart, } from '../server/multipart.js';
 export { generateOpenApiDocument, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiServer, openApiRoute, } from '../server/openapi.js';
 export { bindProcessSignals, type ProcessSignalName, type ProcessSignalsBinding, type ProcessSignalsErrorPhase, type ProcessSignalsOptions, type ShutdownTarget, type SignalSource, } from '../server/process-signals.js';
+export type { ProxyOriginConfig } from '../server/proxy-origin.js';
 export { createRateLimiter, type RateLimitConfig } from '../server/rate-limit.js';
 export { errorResponse, parseBody, respondJson } from '../server/raw.js';
 export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from '../server/realtime.js';

package/dist/entrypoints/server.d.ts.map

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

package/dist/entrypoints/server.js

@@ -335,6 +335,53 @@ function bindSocketRegistry(server, options) {
 }
 // src/server/bun.ts
 import { chmodSync, statSync, unlinkSync } from "node:fs";
+
+// src/server/proxy-origin.ts
+import { z } from "zod";
+var ProtocolSchema = z.enum(["http", "https"]);
+var AuthoritySchema = z.string().min(1).max(1024).regex(/^[^\s/\\?#@,;]+$/);
+var conflictingHeaders = ["forwarded", "x-forwarded-host", "x-forwarded-port"];
+function createProxyOrigin(policy) {
+  const originals = new WeakMap;
+  const original = (request) => originals.get(request) ?? request;
+  return {
+    bind(server) {
+      const requestIP = server.requestIP.bind(server);
+      const timeout = server.timeout.bind(server);
+      const upgrade = server.upgrade.bind(server);
+      server.requestIP = (request) => requestIP(original(request));
+      server.timeout = (request, seconds) => timeout(original(request), seconds);
+      server.upgrade = (request, options) => upgrade(original(request), options);
+    },
+    normalize(request, server) {
+      const peer = server.requestIP(request)?.address;
+      if (!peer || !policy.trustedPeer(peer))
+        return request;
+      const protocol = ProtocolSchema.safeParse(request.headers.get("x-forwarded-proto"));
+      const authority = AuthoritySchema.safeParse(request.headers.get("host"));
+      if (!protocol.success || !authority.success || conflictingHeaders.some((name) => request.headers.has(name))) {
+        return new Response("Invalid proxy origin", { status: 400 });
+      }
+      let origin;
+      try {
+        origin = new URL(`${protocol.data}://${authority.data}`);
+      } catch {
+        return new Response("Invalid proxy origin", { status: 400 });
+      }
+      const url = new URL(request.url);
+      url.protocol = origin.protocol;
+      url.host = origin.host;
+      url.port = origin.port;
+      if (url.href === request.url)
+        return request;
+      const normalized = new Request(url, request);
+      originals.set(normalized, request);
+      return normalized;
+    }
+  };
+}
+
+// src/server/bun.ts
 function reclaimStaleUnixSocket(path) {
   const stats = statSync(path, { throwIfNoEntry: false });
   if (stats === undefined)
@@ -492,17 +539,21 @@ function createServer(config) {
   const handler = createHandler2(config);
   const consumerFetch = config.wrapFetch ? config.wrapFetch(handler) : handler;
   const admittedFetch = lifecycle.wrapFetch(consumerFetch);
+  const proxyOrigin = config.proxyOrigin && createProxyOrigin(config.proxyOrigin);
   const fetch = async (request, server) => {
+    const normalized = proxyOrigin && server ? proxyOrigin.normalize(request, server) : request;
+    if (normalized instanceof Response)
+      return normalized;
     if (socket && socketRoutePrefix) {
-      const pathname = new URL(request.url).pathname;
+      const pathname = new URL(normalized.url).pathname;
       if (pathname.startsWith(socketRoutePrefix)) {
-        return await socket.route.handler(request, {
+        return await socket.route.handler(normalized, {
           params: { socketPath: pathname.slice(socketRoutePrefix.length) },
           server
         });
       }
     }
-    return admittedFetch(request, server);
+    return admittedFetch(normalized, server);
   };
   if (unixPath !== undefined) {
     reclaimStaleUnixSocket(unixPath);
@@ -538,6 +589,7 @@ function createServer(config) {
     });
   }
   const server = runtime;
+  proxyOrigin?.bind(server);
   return {
     url: server.url.toString().replace(/\/$/, ""),
     port: server.port ?? (unixPath !== undefined ? 0 : port),

package/dist/{index-mpg1t7nv.js → index-0z3kfphz.js}

@@ -4,7 +4,7 @@ import {
   AgentSandboxRestrictionSchema2,
   AgentSandboxGradeSchema2,
   AGENT_CODING_TOOL_NAMES
-} from "./index-bm180f2d.js";
+} from "./index-ey15wx6j.js";
 import {
   AgentRecordIdSchema2,
   AgentRecordVersionSchema2,

package/dist/{index-5pbtbce0.js → index-7c957abz.js}

@@ -19,7 +19,7 @@ import {
   appendEventIn,
   ArchiveProjectionSchema,
   createAgentRuntimeStore2
-} from "./index-mpg1t7nv.js";
+} from "./index-0z3kfphz.js";
 import {
   AgentConversationPageSchema2,
   AgentConversationMessagePageSchema2

package/dist/{index-e1sjcjfy.js → index-7r4knwf8.js}

@@ -23,6 +23,62 @@ import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";
 
+// src/process/group-diagnostics.ts
+import { z } from "zod";
+var ObservationSchema = z.object({
+  failure: z.enum(["deadline", "observation"]),
+  groupId: z.number().int().positive(),
+  observations: z.number().int().nonnegative(),
+  lastStates: z.array(z.string().max(32)).max(16),
+  elapsedMs: z.number().int().nonnegative()
+});
+var observations = new WeakMap;
+
+class GroupSettlementError extends Error {
+  constructor(message, observation, cause = observation) {
+    super(`${message}: ${JSON.stringify(observation)}`, { cause });
+    observations.set(this, { ...observation, lastStates: [...observation.lastStates] });
+  }
+}
+function ownData(value, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+function groupSettlementDiagnostics(cause) {
+  const pending = [{ value: cause, depth: 0 }];
+  const seen = new Set;
+  const found = [];
+  for (let visited = 0;pending.length && visited < 32 && found.length < 4; visited++) {
+    const entry = pending.pop();
+    if (!entry || seen.has(entry.value))
+      continue;
+    seen.add(entry.value);
+    try {
+      if (entry.value instanceof Error) {
+        const observation = observations.get(entry.value);
+        if (observation)
+          found.push(observation);
+      }
+      if (!(entry.value instanceof Error) || entry.depth >= 8)
+        continue;
+      if (entry.value instanceof AggregateError) {
+        const errors = ownData(entry.value, "errors");
+        if (Array.isArray(errors)) {
+          for (let index = 0;index < 16; index++) {
+            const value = ownData(errors, String(index));
+            if (value !== undefined)
+              pending.push({ value, depth: entry.depth + 1 });
+          }
+        }
+      }
+      const nested = ownData(entry.value, "cause");
+      if (nested !== undefined)
+        pending.push({ value: nested, depth: entry.depth + 1 });
+    } catch {}
+  }
+  return found;
+}
+
 // src/process/group-presence.ts
 function processGroupExists(pid) {
   try {
@@ -57,36 +113,49 @@ function processGroups(timeoutMs) {
   return new Promise((resolve, reject) => {
     execFile("ps", ["-axo", "pgid=,stat="], { encoding: "utf8", timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 1024 * 1024 }, (error, stdout) => {
       if (error)
-        reject(new Error("Could not observe command process group settlement", { cause: error }));
+        reject(error);
       else
         resolve(stdout);
     });
   });
 }
-async function waitForProcessGroupExit(pid, deadline) {
+async function waitForProcessGroupExit(pid, deadline, killLiveMembers) {
   if (pid === undefined)
     return;
   let observations = 0;
   let lastStates = [];
-  for (;; ) {
-    const remaining = Math.ceil(deadline - performance.now());
-    if (remaining <= 0)
-      throw new Error("Command process group settlement was not confirmed after SIGKILL", {
-        cause: { groupId: pid, observations, lastStates }
-      });
-    if (!processGroupExists(pid))
-      return;
-    const table = await processGroups(remaining);
-    observations++;
-    if (!hasLiveGroupMember(table, pid))
-      return;
-    lastStates = table.split(/\r?\n/).flatMap((row) => {
-      const fields = /^\s*(\d+)\s+(\S+)\s*$/.exec(row);
-      return Number(fields?.[1]) === pid ? [fields?.[2] ?? "unknown"] : [];
-    }).slice(0, 16);
-    if (!processGroupExists(pid))
-      return;
-    await sleep(Math.min(5, Math.max(0, deadline - performance.now())));
+  const startedAt = performance.now();
+  const observation = () => ({
+    groupId: pid,
+    observations,
+    lastStates,
+    elapsedMs: Math.max(0, Math.ceil(performance.now() - startedAt))
+  });
+  try {
+    for (;; ) {
+      const remaining = Math.ceil(deadline - performance.now());
+      if (remaining <= 0)
+        throw new GroupSettlementError("Command process group settlement was not confirmed after SIGKILL", { ...observation(), failure: "deadline" });
+      if (!processGroupExists(pid))
+        return;
+      const table = await processGroups(remaining);
+      observations++;
+      if (!hasLiveGroupMember(table, pid))
+        return;
+      lastStates = table.split(/\r?\n/).flatMap((row) => {
+        const fields = /^\s*(\d+)\s+(\S+)\s*$/.exec(row);
+        return Number(fields?.[1]) === pid ? [(fields?.[2] ?? "unknown").slice(0, 32)] : [];
+      }).slice(0, 16);
+      if (!processGroupExists(pid))
+        return;
+      if (killLiveMembers && performance.now() < deadline && !await killLiveMembers())
+        return;
+      await sleep(Math.min(5, Math.max(0, deadline - performance.now())));
+    }
+  } catch (cause) {
+    if (cause instanceof GroupSettlementError)
+      throw cause;
+    throw new GroupSettlementError("Could not observe command process group settlement", { ...observation(), failure: "observation" }, cause);
   }
 }
 
@@ -151,7 +220,7 @@ async function killAndSettleGroup(pid, deadline, cleanupTimeoutMs) {
   const cleanupDeadline = Math.min(deadline, performance.now() + cleanupTimeoutMs);
   const signalled = await signalUntilSettled(pid, "SIGKILL", cleanupDeadline);
   if (signalled)
-    await waitForProcessGroupExit(pid, cleanupDeadline);
+    await waitForProcessGroupExit(pid, cleanupDeadline, () => signalUntilSettled(pid, "SIGKILL", cleanupDeadline));
   return signalled;
 }
 async function stopCommandGroup(stop) {
@@ -235,7 +304,9 @@ async function stopLeaderAlone(stop) {
   return send("SIGKILL") || signalled;
 }
 function commandCleanupError(cause) {
-  return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
+  const observations = groupSettlementDiagnostics(cause);
+  const message = observations.length ? `Command cleanup did not complete: ${JSON.stringify(observations)}` : "Command cleanup did not complete";
+  return new NativeCommandError2("COMMAND_CLEANUP", message, {
     cause
   });
 }

package/dist/{index-bm180f2d.js → index-ey15wx6j.js}

@@ -7,7 +7,7 @@ import {
 import {
   CommandStopped,
   startNativeCommand
-} from "./index-e1sjcjfy.js";
+} from "./index-7r4knwf8.js";
 import {
   NumericFileHandle,
   descriptorPath,

package/dist/{index-9ket8wzx.js → index-mnk5vgdr.js}

@@ -17,7 +17,7 @@ import {
   replaceMessage,
   ArchiveSpillSchema,
   createAgentRuntimeStore2
-} from "./index-mpg1t7nv.js";
+} from "./index-0z3kfphz.js";
 
 // src/agent-runtime/store-memory.ts
 import { z as z2 } from "zod";

package/dist/process/group-diagnostics.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+declare const ObservationSchema: z.ZodObject<{
+    failure: z.ZodEnum<{
+        deadline: "deadline";
+        observation: "observation";
+    }>;
+    groupId: z.ZodNumber;
+    observations: z.ZodNumber;
+    lastStates: z.ZodArray<z.ZodString>;
+    elapsedMs: z.ZodNumber;
+}, z.core.$strip>;
+type Observation = z.infer<typeof ObservationSchema>;
+/** Only this internal error carries process-state diagnostics safe to promote. */
+export declare class GroupSettlementError extends Error {
+    constructor(message: string, observation: Observation, cause?: unknown);
+}
+/** Bounded cause traversal; arbitrary caller messages never become cleanup diagnostics. */
+export declare function groupSettlementDiagnostics(cause: unknown): Observation[];
+export {};
+//# sourceMappingURL=group-diagnostics.d.ts.map

package/dist/process/group-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-diagnostics.d.ts","sourceRoot":"","sources":["../../src/process/group-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,iBAAiB;;;;;;;;;iBAMrB,CAAC;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAGrD,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,GAAE,OAAqB,EAKlF;CACF;AAQD,2FAA2F;AAC3F,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,EAAE,CA+BxE"}

package/dist/process/group-settlement.d.ts

@@ -1,5 +1,5 @@
 /** `killpg(..., 0)` also sees Linux zombies; only live members can still perform work. */
 export declare function hasLiveGroupMember(table: string, group: number): boolean;
 /** A delivered SIGKILL is asynchronous; do not report cleanup until every group member is dead. */
-export declare function waitForProcessGroupExit(pid: number | undefined, deadline: number): Promise<void>;
+export declare function waitForProcessGroupExit(pid: number | undefined, deadline: number, killLiveMembers?: () => Promise<boolean>): Promise<void>;
 //# sourceMappingURL=group-settlement.d.ts.map

package/dist/process/group-settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAIA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAmBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA0Bf"}
+{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAKA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAgBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAmDf"}

package/dist/process/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAIpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAsCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAKpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAyCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAQtE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}

package/dist/server/bun.d.ts

@@ -1,3 +1,4 @@
+import { type ProxyOriginConfig } from './proxy-origin.js';
 import { type ManagedServerHandle } from './shutdown.js';
 import type { SocketIOServerLifecycle } from './socket-io.js';
 import type { FetchComposition, FetchHandler, HandlerConfig, RawRoute, RawRouteContext } from './types.js';
@@ -26,6 +27,14 @@ export type UnixListenConfig = string | {
 };
 /** Bun-specific server config layered over the Fetch-clean handler config. */
 export interface BunServerConfig extends BunHandlerConfig, BunFetchComposition {
+    /**
+     * Restore the external scheme behind one trusted TCP ingress, before composition.
+     * The ingress must overwrite Host and X-Forwarded-Proto and remove Forwarded,
+     * X-Forwarded-Host and X-Forwarded-Port. Trusted requests require exactly one
+     * `http` or `https` proto; malformed/conflicting headers receive 400.
+     * Host/tenant authorization remains application-owned. Independent of trustProxy.
+     */
+    proxyOrigin?: ProxyOriginConfig;
     port?: number;
     hostname?: string;
     /**

package/dist/server/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AA+F7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAgMrE"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AA+F7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqMrE"}

package/dist/server/proxy-origin.d.ts

@@ -0,0 +1,12 @@
+import type { BunServer } from './bun.js';
+/** One TCP ingress that overwrites Host/proto and strips competing URL headers. */
+export interface ProxyOriginConfig {
+    /** Match the real socket peer, never a forwarded client IP. */
+    trustedPeer: (socketIp: string) => boolean;
+}
+/** Bun associates requestIP, timeout and upgrade with the original native request. */
+export declare function createProxyOrigin(policy: ProxyOriginConfig): {
+    bind(server: BunServer): void;
+    normalize(request: Request, server: BunServer): Request | Response;
+};
+//# sourceMappingURL=proxy-origin.d.ts.map

package/dist/server/proxy-origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-origin.d.ts","sourceRoot":"","sources":["../../src/server/proxy-origin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC5C;AAUD,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB;IAKvD,IAAI,SAAS,SAAS,GAAG,IAAI;IAQ7B,SAAS,UAAU,OAAO,UAAU,SAAS,GAAG,OAAO,GAAG,QAAQ;EAgCrE"}

package/llms/server.2.txt

@@ -18,6 +18,137 @@ Also read:
 # Guide: HTTP server  (docs/guide/server.md)  (continued)
 ==============================================================================
 
+## Raw routes
+
+Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
+signature verification, static files, the Socket.IO endpoint. `rawRoutes` are
+plain `Request → Response` handlers, matched by the same router (shared CORS and
+`onRequest`) but with no schema parsing and no `beforeHandle` gate — a raw route
+authorises itself.
+
+```ts
+createServer({
+  services,
+  rawRoutes: [
+    {
+      method: 'GET',
+      path: '/health',
+      handler: () => Response.json({ status: 'ok' }),
+    },
+    {
+      method: 'POST',
+      path: '/webhooks/:provider',
+      serviceName: 'webhooks',
+      action: 'receive',
+      handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
+    },
+  ],
+})
+```
+
+`serviceName` and `action` are optional observability identity. Declare
+`serviceName` when audit, logging, sampling or another cross-cutting policy
+groups this raw route with a service; add `action` when the policy needs an
+operation within that service. Stitchkit never derives either from `path`.
+`action` without `serviceName`, and empty identity strings, fail at startup.
+
+A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
+wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
+`ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
+deep-link fallback). List more specific routes before the wildcard — the first
+match wins. `staticRoute()` builds a raw route that serves a directory.
+
+At startup Stitchkit rejects exact duplicates, equivalent parameter shapes
+(`/users/:id` vs `/users/:userId`) and any later raw route completely hidden by
+an earlier raw route. Partial overlap stays legal, including the recommended
+specific-before-wildcard order. `GET` and `HEAD` remain independent because that
+is how the actual raw matcher dispatches them. Raw-vs-contract overlap remains a
+startup diagnostic naming the bypassed contract identity and scope.
+
+### Raw-route helpers
+
+A raw route gives up the contract pipeline, so three things get re-implemented in
+every one. `stitchkit/server` ships them — conveniences, not a second pipeline
+(no auth, no schema gate beyond `parseBody`):
+
+```ts
+import { respondJson, errorResponse, parseBody, badRequest } from 'stitchkit/server'
+
+handler: async (req) => {
+  try {
+    const body = await parseBody(req, MySchema)      // typed value, or null (no throw)
+    if (!body) throw badRequest('invalid body')      // helpers THROW an AppError
+    return respondJson(await myService(body))         // JSON; 204 when null/undefined
+  } catch (err) {
+    return errorResponse(err)                         // same envelope as a contract route
+  }
+}
+```
+
+The error helpers (`badRequest`, `notFound`, …) **throw** an `AppError`, so raise
+them inside the `try` and let `errorResponse(err)` render it — that runs any
+thrown value through the framework's `normalizeError`, so a raw route returns the
+**identical** `{ error: { code, message, … } }` shape (and `x-request-id`) a
+contract route does.
+
+### Serving files & Range requests
+
+`staticRoute` is basic on purpose — it reads the whole file into memory and has
+no `Range` or conditional support; put a CDN in front, or use it for small web
+assets. To serve **media** (video / audio / large downloads) that a browser must
+seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
+and speaks the conditional-request half of RFC 7233 / 9110:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { implement, serveFile } from 'stitchkit/server'
+import { z } from 'zod'
+
+const MediaParams = z.object({ id: z.string() })
+const media = defineContract({ prefix: 'media' }, {
+  download: {
+    method: 'GET', path: '/:id', desc: 'Download media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+  inspect: {
+    method: 'HEAD', path: '/:id', desc: 'Inspect media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+})
+
+const mediaService = implement(media, {
+  download: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
+  inspect: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
+})
+```
+
+GET and HEAD are separate operations deliberately: declaring GET never creates
+a hidden HEAD alias. Both travel through the normal contract router, params,
+lifecycle/RBAC and request logging. A HEAD handler may inspect the raw query via
+`ctx.req.url`, but cannot declare a request input schema or body.
+
+`serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
+(full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
+(`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
+It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
+`If-Range` keeps a changing file from being stitched from stale + fresh bytes),
+and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
+pass `disposition` / `cacheControl` / `etag: false`, via the options.
+
+Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
+headers. stitchkit therefore exposes the download-relevant ones by default
+(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
+download cannot recover the file's name. Override with `cors.exposeHeaders`
+(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
+emit none.
+
+`serveFile` takes an explicit `path` and trusts it — **the caller owns
+containment**. For a URL-derived path use `staticRoute` (which enforces it) or
+`isWithinDir` first. The byte-range parser is exported on its own as
+`parseByteRange(header, size)` for direct use and testing. → ADR 0023.
+
 ## Server primitives
 
 `stitchkit/server` also exports the primitives most APIs need. Each is a small,

package/llms/server.5.txt

@@ -65,6 +65,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `ProxyOriginConfig` | _type_ | explicit real-peer trust for Bun `createServer({ proxyOrigin })`; strict external-scheme normalization before composition — [details](../guide/server.md#external-origin-behind-a-trusted-proxy) |
 | `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |

package/llms/server.txt

@@ -268,6 +268,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
 | `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
 | `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
+| `proxyOrigin` | Bun TCP ingress policy: `{ trustedPeer(socketIp) }` restores the external scheme before all composition; independent of client-IP `trustProxy` |
 | `socket` | full Stitchkit Socket.IO handle; route, default WebSocket handler and shutdown are mounted once |
 | `websocket` | custom Bun WebSocket handler; with `socket`, this is the explicit composed handler |
 | `development` / `bun` | passthrough to `Bun.serve` |
@@ -276,6 +277,60 @@ Native Bun `routes` are intentionally not accepted: Bun matches them before
 `fetch`, so they could bypass shutdown admission. Use `rawRoutes`; they retain
 the Fetch `Request → Response` model and participate in lifecycle tracking.
 
+### External origin behind a trusted proxy
+
+An HTTPS ingress often forwards plain HTTP to Bun. `trustProxy` trusts client-IP
+headers only; it does not change `Request.url`. Opt into the separate URL policy:
+
+```ts
+import { createServer, isLoopbackAddress } from 'stitchkit/server'
+
+const server = createServer({
+  hostname: '127.0.0.1',
+  port: 3000,
+  proxyOrigin: { trustedPeer: isLoopbackAddress },
+  services,
+})
+```
+
+The predicate receives the **real TCP peer**, never `X-Forwarded-For` or
+`X-Real-IP`. Match only the ingress you control. Loopback is appropriate only
+when other local processes are trusted. Unmatched peers, missing peer metadata
+and the default configuration ignore URL forwarding headers. Unix listeners have
+no TCP peer and do not use this policy. This option belongs to Bun `createServer`,
+not the Fetch-clean `createHandler` or Node `serveNode`.
+
+The trusted ingress must overwrite `Host` with the external authority and
+`X-Forwarded-Proto` with exactly `http` or `https`. It must remove `Forwarded`,
+`X-Forwarded-Host` and `X-Forwarded-Port`; their presence, a missing/invalid
+proto, a list of values or a malformed Host returns HTTP 400 before application
+code. Header names are case-insensitive; proto values are lowercase. Multiple
+ingress chains require a single sanitizing ingress at this boundary.
+
+For an nginx HTTPS terminator, the relevant forwarding settings are:
+
+```nginx
+proxy_set_header Host $http_host;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header Forwarded "";
+proxy_set_header X-Forwarded-Host "";
+proxy_set_header X-Forwarded-Port "";
+```
+
+The normalized `Request.url` reaches `wrapFetch`, hooks, contracts, raw routes,
+and the managed Socket.IO route. It preserves the path/query, wire authority
+(including explicit ports), method, body, headers and linked cancellation signal.
+Request cloning uses the normalized URL. The same runtime handle resolves
+`requestIP`, `timeout` and `upgrade` against the original native request, retaining
+WebSocket and shutdown behavior.
+
+This is a scheme normalization policy, **not host authorization**. Applications
+must retain their hostname/tenant allowlist and exact same-origin checks for
+Origin and Referer. The TLS terminator must reject SNI/Host mismatches before
+forwarding; a plain-HTTP Bun listener cannot observe the TLS SNI. The normalizer
+does not accept `X-Forwarded-Host`, authorize a foreign Host, or treat HTTP and
+HTTPS as aliases.
+
 ### Local daemon over a unix socket
 
 A local daemon whose door is a socket file needs no TCP port at all:
@@ -863,134 +918,3 @@ file: (ctx) => {
 `Response` is forwarded verbatim. Request headers are not relayed, so a `Range`
 sent to the proxy does not reach the origin and the full body comes back.
 → ADR 0038.
-
-## Raw routes
-
-Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
-signature verification, static files, the Socket.IO endpoint. `rawRoutes` are
-plain `Request → Response` handlers, matched by the same router (shared CORS and
-`onRequest`) but with no schema parsing and no `beforeHandle` gate — a raw route
-authorises itself.
-
-```ts
-createServer({
-  services,
-  rawRoutes: [
-    {
-      method: 'GET',
-      path: '/health',
-      handler: () => Response.json({ status: 'ok' }),
-    },
-    {
-      method: 'POST',
-      path: '/webhooks/:provider',
-      serviceName: 'webhooks',
-      action: 'receive',
-      handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
-    },
-  ],
-})
-```
-
-`serviceName` and `action` are optional observability identity. Declare
-`serviceName` when audit, logging, sampling or another cross-cutting policy
-groups this raw route with a service; add `action` when the policy needs an
-operation within that service. Stitchkit never derives either from `path`.
-`action` without `serviceName`, and empty identity strings, fail at startup.
-
-A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
-wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
-`ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
-deep-link fallback). List more specific routes before the wildcard — the first
-match wins. `staticRoute()` builds a raw route that serves a directory.
-
-At startup Stitchkit rejects exact duplicates, equivalent parameter shapes
-(`/users/:id` vs `/users/:userId`) and any later raw route completely hidden by
-an earlier raw route. Partial overlap stays legal, including the recommended
-specific-before-wildcard order. `GET` and `HEAD` remain independent because that
-is how the actual raw matcher dispatches them. Raw-vs-contract overlap remains a
-startup diagnostic naming the bypassed contract identity and scope.
-
-### Raw-route helpers
-
-A raw route gives up the contract pipeline, so three things get re-implemented in
-every one. `stitchkit/server` ships them — conveniences, not a second pipeline
-(no auth, no schema gate beyond `parseBody`):
-
-```ts
-import { respondJson, errorResponse, parseBody, badRequest } from 'stitchkit/server'
-
-handler: async (req) => {
-  try {
-    const body = await parseBody(req, MySchema)      // typed value, or null (no throw)
-    if (!body) throw badRequest('invalid body')      // helpers THROW an AppError
-    return respondJson(await myService(body))         // JSON; 204 when null/undefined
-  } catch (err) {
-    return errorResponse(err)                         // same envelope as a contract route
-  }
-}
-```
-
-The error helpers (`badRequest`, `notFound`, …) **throw** an `AppError`, so raise
-them inside the `try` and let `errorResponse(err)` render it — that runs any
-thrown value through the framework's `normalizeError`, so a raw route returns the
-**identical** `{ error: { code, message, … } }` shape (and `x-request-id`) a
-contract route does.
-
-### Serving files & Range requests
-
-`staticRoute` is basic on purpose — it reads the whole file into memory and has
-no `Range` or conditional support; put a CDN in front, or use it for small web
-assets. To serve **media** (video / audio / large downloads) that a browser must
-seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
-and speaks the conditional-request half of RFC 7233 / 9110:
-
-```ts
-import { defineContract } from 'stitchkit/contract'
-import { implement, serveFile } from 'stitchkit/server'
-import { z } from 'zod'
-
-const MediaParams = z.object({ id: z.string() })
-const media = defineContract({ prefix: 'media' }, {
-  download: {
-    method: 'GET', path: '/:id', desc: 'Download media',
-    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
-  },
-  inspect: {
-    method: 'HEAD', path: '/:id', desc: 'Inspect media',
-    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
-  },
-})
-
-const mediaService = implement(media, {
-  download: ({ req, params }) =>
-    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
-  inspect: ({ req, params }) =>
-    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
-})
-```
-
-GET and HEAD are separate operations deliberately: declaring GET never creates
-a hidden HEAD alias. Both travel through the normal contract router, params,
-lifecycle/RBAC and request logging. A HEAD handler may inspect the raw query via
-`ctx.req.url`, but cannot declare a request input schema or body.
-
-`serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
-(full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
-(`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
-It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
-`If-Range` keeps a changing file from being stitched from stale + fresh bytes),
-and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
-pass `disposition` / `cacheControl` / `etag: false`, via the options.
-
-Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
-headers. stitchkit therefore exposes the download-relevant ones by default
-(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
-download cannot recover the file's name. Override with `cors.exposeHeaders`
-(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
-emit none.
-
-`serveFile` takes an explicit `path` and trusts it — **the caller owns
-containment**. For a URL-derived path use `staticRoute` (which enforces it) or
-`isWithinDir` first. The byte-range parser is exported on its own as
-`parseByteRange(header, size)` for direct use and testing. → ADR 0023.

package/llms-full.txt

@@ -1369,6 +1369,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
 | `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
 | `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
+| `proxyOrigin` | Bun TCP ingress policy: `{ trustedPeer(socketIp) }` restores the external scheme before all composition; independent of client-IP `trustProxy` |
 | `socket` | full Stitchkit Socket.IO handle; route, default WebSocket handler and shutdown are mounted once |
 | `websocket` | custom Bun WebSocket handler; with `socket`, this is the explicit composed handler |
 | `development` / `bun` | passthrough to `Bun.serve` |
@@ -1377,6 +1378,60 @@ Native Bun `routes` are intentionally not accepted: Bun matches them before
 `fetch`, so they could bypass shutdown admission. Use `rawRoutes`; they retain
 the Fetch `Request → Response` model and participate in lifecycle tracking.
 
+### External origin behind a trusted proxy
+
+An HTTPS ingress often forwards plain HTTP to Bun. `trustProxy` trusts client-IP
+headers only; it does not change `Request.url`. Opt into the separate URL policy:
+
+```ts
+import { createServer, isLoopbackAddress } from 'stitchkit/server'
+
+const server = createServer({
+  hostname: '127.0.0.1',
+  port: 3000,
+  proxyOrigin: { trustedPeer: isLoopbackAddress },
+  services,
+})
+```
+
+The predicate receives the **real TCP peer**, never `X-Forwarded-For` or
+`X-Real-IP`. Match only the ingress you control. Loopback is appropriate only
+when other local processes are trusted. Unmatched peers, missing peer metadata
+and the default configuration ignore URL forwarding headers. Unix listeners have
+no TCP peer and do not use this policy. This option belongs to Bun `createServer`,
+not the Fetch-clean `createHandler` or Node `serveNode`.
+
+The trusted ingress must overwrite `Host` with the external authority and
+`X-Forwarded-Proto` with exactly `http` or `https`. It must remove `Forwarded`,
+`X-Forwarded-Host` and `X-Forwarded-Port`; their presence, a missing/invalid
+proto, a list of values or a malformed Host returns HTTP 400 before application
+code. Header names are case-insensitive; proto values are lowercase. Multiple
+ingress chains require a single sanitizing ingress at this boundary.
+
+For an nginx HTTPS terminator, the relevant forwarding settings are:
+
+```nginx
+proxy_set_header Host $http_host;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header Forwarded "";
+proxy_set_header X-Forwarded-Host "";
+proxy_set_header X-Forwarded-Port "";
+```
+
+The normalized `Request.url` reaches `wrapFetch`, hooks, contracts, raw routes,
+and the managed Socket.IO route. It preserves the path/query, wire authority
+(including explicit ports), method, body, headers and linked cancellation signal.
+Request cloning uses the normalized URL. The same runtime handle resolves
+`requestIP`, `timeout` and `upgrade` against the original native request, retaining
+WebSocket and shutdown behavior.
+
+This is a scheme normalization policy, **not host authorization**. Applications
+must retain their hostname/tenant allowlist and exact same-origin checks for
+Origin and Referer. The TLS terminator must reject SNI/Host mismatches before
+forwarding; a plain-HTTP Bun listener cannot observe the TLS SNI. The normalizer
+does not accept `X-Forwarded-Host`, authorize a foreign Host, or treat HTTP and
+HTTPS as aliases.
+
 ### Local daemon over a unix socket
 
 A local daemon whose door is a socket file needs no TCP port at all:
@@ -21245,6 +21300,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `ProxyOriginConfig` | _type_ | explicit real-peer trust for Bun `createServer({ proxyOrigin })`; strict external-scheme normalization before composition — [details](../guide/server.md#external-origin-behind-a-trusted-proxy) |
 | `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |

package/llms.txt

@@ -23,7 +23,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.7 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.1 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 42.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.3 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.3 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 45.9 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 42.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 35.6 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.110.5",
+  "version": "0.110.6",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",