stitchkit 0.45.0 → 0.46.0

package/llms-full.txt

@@ -677,7 +677,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `maxUploadBytes` | default multipart upload cap (bytes); per-route `EndpointDef.maxUploadBytes` overrides |
 | `maxJsonBodyBytes` | optional JSON body cap (bytes); per-route value overrides; unset preserves existing behaviour |
 | `port` / `hostname` | listen address — port defaults to `3000` |
-| `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }` |
+| `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }`. `origin` is **required** when `cors` is present: pass an explicit origin (or list), or `'*'` to deliberately allow every origin — an origin-less config is a construction error, never a silent wildcard. Omit `cors` entirely to emit no CORS headers. |
 | `hooks` | lifecycle hooks (see below) |
 | `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 |
@@ -685,6 +685,34 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
 | `routes` / `development` / `bun` | passthrough to `Bun.serve` |
 
+### Trusted HTTPS in development
+
+Stitchkit does not own local certificate generation or a frontend development
+server. When a device or browser feature requires a secure context, generate a
+trusted certificate outside the application (for example with `mkcert`) and pass
+its files through the Bun server boundary:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { createServer } from 'stitchkit/server'
+
+createServer({
+  services,
+  hostname: '0.0.0.0',
+  bun: {
+    tls: {
+      cert: readFileSync('./certs/dev.pem'),
+      key: readFileSync('./certs/dev-key.pem'),
+    },
+  },
+})
+```
+
+Trust the certificate authority on each test device and configure the frontend's
+HTTPS mode in that frontend project. Certificate renewal, interface discovery
+and device onboarding remain application infrastructure rather than framework
+or starter behavior.
+
 ### Request logging
 
 `logging: true` is shorthand for `logging: {}` — **any object turns logging
@@ -1207,7 +1235,7 @@ The client side is [`parseSSE`](./client.md#sse).
 ```ts
 import { parseMultipart } from 'stitchkit/server'
 
-const { file, fields } = await parseMultipart(req, { maxBytes: 10_000_000 })
+const { file, fields } = await parseMultipart(req, 'file', undefined, 10_000_000)
 ```
 
 When an endpoint declares `multipart`, the framework parses the upload for you
@@ -1232,8 +1260,11 @@ createServer({ services, maxUploadBytes: 50 * 1024 * 1024 })
 ```ts
 import { createRateLimiter } from 'stitchkit/server'
 
-const limiter = createRateLimiter({ capacity: 60, refillPerSecond: 1 })
-// in onRequest: if (!limiter.take(ip)) return new Response('Too many', { status: 429 })
+const limiter = createRateLimiter()
+// in onRequest:
+if (!limiter.check(ip, { window: 60_000, max: 60 })) {
+  return new Response('Too many', { status: 429 })
+}
 ```
 
 ### Event bus
@@ -2259,6 +2290,15 @@ timeouts, redirect count and body size are bounded. Its bounded cache respects
 `Last-Modified`, coalesces concurrent misses and reports sanitized cache events;
 invalid or unavailable identity receives only a short fail-closed cache entry.
 
+Resolution itself is rate-limited on two levels (`CimdCachePolicy`):
+`maxResolutionsPerClient` (default 10) bounds ONE `client_id` per
+`resolutionWindowMs` window (default 60 s) — a client whose document disables
+caching burns its own budget, not the server's — while `maxResolutions`
+(default 120) caps the server-wide outbound rate as the flood backstop.
+Positive and negative cache entries keep separate pools of `maxEntries` each,
+so a flood of unresolvable ids cannot evict warmed clients and a burst of
+successes cannot reset a failing client's backoff.
+
 ### Authorization hardening (MCP 2026-07-28)
 
 - **`iss` on every authorization response (RFC 9207, SEP-2468).** Success *and*
@@ -2586,6 +2626,11 @@ mountMcp(server, services, { hooks: createToolLogger() })
 // [tool] warn get_widget (widgets.get) NOT_FOUND 4ms
 ```
 
+By default the line goes to `console.error` — **stderr, never stdout**. That is
+deliberate: in a stdio-MCP server stdout is the JSON-RPC protocol channel, and a
+log line written there corrupts the stream. If you pass your own `log`, keep it
+off stdout for any stdio deployment.
+
 Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
 structured `ToolCallRecord`. That record carries `traceId` whenever an
 observability context is active, so a tool call made inside an HTTP request
@@ -2798,6 +2843,8 @@ fallback, heartbeats, acks, a mature client. stitchkit does not ship its own
 WebSocket engine; it ships thin, typed wrappers over Socket.IO and a bridge that
 syncs socket events into the TanStack Query cache. See
 [ADR 0008](../decisions/0008-thin-wrappers.md).
+The separate contract shape and rejection ownership are recorded in
+[ADR 0069](../decisions/0069-realtime-contracts-validate-without-owning-delivery.md).
 
 ## Zod-first event contract
 
@@ -2870,6 +2917,16 @@ createServer({
 realtime.emit('note:created', note)
 ```
 
+The canonical room-broadcast example below is executed by the test suite. Its
+body is kept byte-identical to `packages/core/examples/realtime-room.ts`.
+
+```ts canonical-realtime-room
+export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
+  const note = { id: 'note-1', text: 'Ready' };
+  realtime.to('general').emit('note:created', note);
+}
+```
+
 | Handle field | Purpose |
 |--------------|---------|
 | `io` | raw Socket.IO server for middleware, handshake auth and transport ownership |
@@ -3127,11 +3184,9 @@ policies; this helper only applies declared CRUD semantics.
 
 ## Raw binary lane (Bun)
 
-Socket.IO carries binary fine — for most streams a binary event (`pcm(frame)`)
-is enough. But a *truly* high-throughput binary channel (video, large
-transfers) may want a raw WebSocket with no Socket.IO framing, on the **same**
-port. On Bun that is awkward: `Bun.serve` has a single `websocket` handler, and
-`createSocketIOServer().websocket` claims it.
+For a high-throughput raw binary channel beside Socket.IO, use the orthogonal
+composition boundary from
+[ADR 0020](../decisions/0020-raw-websocket-lane.md).
 
 `composeWebSocketHandlers` composes that one handler from several lanes. A raw
 lane stamps its own marker onto `ws.data` at upgrade and is matched positively;
@@ -3414,9 +3469,11 @@ pick the scheme), and checks `exp` and `nbf`.
 
 ```ts
 import { verifyJwt, extractToken } from 'stitchkit/server'
+import { env } from './env'
 
 const token = extractToken(req)           // from Authorization, or a cookie name
-const payload = await verifyJwt(token, process.env.JWT_SECRET!)
+if (!token) throw unauthorized('Bearer token is required')
+const payload = await verifyJwt(token, env.JWT_SECRET)
 ```
 
 `extractToken(req, cookieName?)` reads a bearer token from the `Authorization`
@@ -3614,6 +3671,7 @@ const onError = createErrorHook({
     NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
+    REALTIME_CONTRACT_VIOLATION: 'internal',
   } satisfies Record<StitchErrorCode, string>,
   // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
   // correlation id in the envelope. Declaring it is optional.
@@ -3967,8 +4025,10 @@ each request.
 
 A payload goes into an audit row only after `sanitizePayload`:
 
-- **secret-named keys are masked** — `password`, `token`, `apiKey`, `secret`,
-  `authorization`, `cookie`, … (value → `[redacted]`);
+- **secret-named keys are masked** — a key whose words include a secret term is
+  redacted (`password`, `sessionToken`, `X-Api-Key`, `authorization`, `cookie`,
+  …), while identifiers that merely contain one (`authorId`, `sessionCount`,
+  `tokenizer`) survive;
 - **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
@@ -4564,7 +4624,7 @@ current one *up to* your target, and apply each snippet.
    (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
    `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
 
-## Unreleased breaking migrations
+## Released migration: 0.44.0
 
 ### MCP TypeScript SDK v2 and protocol `2026-07-28`
 
@@ -4759,14 +4819,29 @@ implemented or advertised.
 3. Delete all session mode, event-store and session-id code.
 4. Move OAuth client policy under `clientRegistration`; publish CIMD or enable
    DCR explicitly.
-5. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
+5. Make `authorizeUser` return the exact consented scope subset. The framework
+   validates that it is a subset of the request before saving the authorization
+   code:
+
+   ```ts
+   // before
+   authorizeUser: async () => ({ userId })
+
+   // after
+   authorizeUser: async (_req, request) => ({
+     userId,
+     approvedScopes: request.scope?.split(' ') ?? [],
+   })
+   ```
+
+6. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
    multimodal tool and every MCP App resource you use.
-6. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
+7. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
    only if `legacy: 'serve'` is part of your support policy.
-7. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
+8. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
    must continue to work without either MCP package.
 
-## Historical breaking migrations through 0.43.1
+## Historical breaking migrations through 0.44.0
 
 HTTP observability now completes inside the framework handler instead of a
 nested fetch wrapper. Configure request and tool sinks explicitly:
@@ -5252,6 +5327,17 @@ The browser-and-server entrypoint. Re-exports everything from
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
 | `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
+| `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
+| `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
+| `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
+| `RealtimeEventArguments` | _type_ | tuple inferred from an event definition |
+| `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
+| `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
+| `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
+| `RealtimeRejectDirection` | _type_ | server/client inbound/outbound rejection direction |
+| `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
+| `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
+| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
@@ -5469,6 +5555,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `parseMultipart` | function | parse a `multipart/form-data` request — [guide](../guide/server.md#multipart) |
 | `createRateLimiter` | function | token-bucket rate limiting — [guide](../guide/server.md#rate-limiting) |
 | `createCache` | function | an in-memory TTL cache |
+| `CacheOptions` | _type_ | bounded-cache options, including the maximum retained entry count |
 | `cacheHeaders` | function | build a `Cache-Control` header |
 | `EventBusOptions` | _type_ | options for `createEventBus` |
 | `EventHandler` | _type_ | one event-bus subscriber |
@@ -5596,6 +5683,7 @@ payload.
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
+| `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
 | `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
 | `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
 | `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
@@ -5626,7 +5714,7 @@ payload.
 | `CimdClientMetadataFetcher` | _type_ | injectable secure network boundary for metadata loading |
 | `CimdFetchResponse` | _type_ | bounded metadata fetch result passed across the injectable network boundary |
 | `CimdFetchPolicy` | _type_ | CIMD timeout, redirect and size limits |
-| `CimdCachePolicy` | _type_ | bounded HTTP-aware positive/negative cache policy |
+| `CimdCachePolicy` | _type_ | bounded HTTP-aware cache policy: separate positive/negative pools (`maxEntries`), per-client and server-wide resolution rate limits (`maxResolutionsPerClient` / `maxResolutions` per `resolutionWindowMs`) |
 | `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
 | `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
@@ -5739,7 +5827,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic
 core plus a Node HTTP adapter — [ADR 0013](../decisions/0013-runtime-agnostic-core.md),
-[deployment guide](../guide/testing-and-deployment.md#node). Re-exports the
+[deployment guide](../guide/testing-and-deployment.md#deploy-on-node). Re-exports the
 runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 
 | Export | Kind | Summary |

package/llms.txt

@@ -13,7 +13,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program
 - [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
 - [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry
-- [Observability](https://github.com/max-listov/stitchkit/blob/master/docs/guide/observability.md): request and tool-call logging via hooks, W3C trace context, createAuditHook
+- [Observability](https://github.com/max-listov/stitchkit/blob/master/docs/guide/observability.md): request and tool-call observability, W3C trace context, createObservability
 - [Testing & deployment](https://github.com/max-listov/stitchkit/blob/master/docs/guide/testing-and-deployment.md): in-process testing; deploying on Bun and on Node (serveNode)
 - [Multi-tenant](https://github.com/max-listov/stitchkit/blob/master/docs/guide/multi-tenant.md): a /tenants/:id/… scenario end-to-end — scopePrefixes, scoped client, extend
 - [Frontend integrations](https://github.com/max-listov/stitchkit/blob/master/docs/guide/frontend-integrations.md): React Router resource routes and a separate Vite development proxy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "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",
@@ -88,7 +88,7 @@
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
     "dev": "bun run build:js -- --watch",
-    "prepublishOnly": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
+    "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
     "consumer-lane": "bun scripts/consumer-lane/run.mjs",

package/dist/index-frfyw9fa.js

@@ -1,33 +0,0 @@
-// src/tools/json-schema.ts
-import { z } from "zod";
-function toJsonSchema(schema, io, unrepresentable = "throw", target = "draft-2020-12") {
-  return z.toJSONSchema(schema, {
-    io,
-    target,
-    unrepresentable,
-    cycles: "ref"
-  });
-}
-function isObjectNode(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function jsonSchemaFields(jsonSchema) {
-  const properties = jsonSchema.properties;
-  if (!isObjectNode(properties))
-    return [];
-  const required = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required.filter((k) => typeof k === "string") : []);
-  const fields = [];
-  for (const [name, raw] of Object.entries(properties)) {
-    const schema = isObjectNode(raw) ? raw : {};
-    const description = typeof schema.description === "string" ? schema.description : undefined;
-    fields.push({
-      name,
-      schema,
-      required: required.has(name),
-      ...description && { description }
-    });
-  }
-  return fields;
-}
-
-export { toJsonSchema, jsonSchemaFields };

package/dist/index-x3fcszf8.js

@@ -1,8 +0,0 @@
-// src/internal/within-dir.ts
-import { sep } from "node:path";
-function isWithinDir(root, target) {
-  const base = root.endsWith(sep) ? root.slice(0, -sep.length) : root;
-  return target === root || target === base || target.startsWith(base + sep);
-}
-
-export { isWithinDir };