stitchkit 0.50.0 → 0.52.0

package/llms-full.txt

@@ -737,7 +737,12 @@ Three boundaries worth knowing:
   it). It degrades to `unknown`, so it can no longer pose as a `string`; using it
   in a typed position fails.
 - The map states what **your** `beforeHandle` / `createAuthHook.inject` puts on
-  the context. The framework does not verify that claim (→ ADR 0075).
+  the context. The framework does not verify a hand-written claim (→ ADR 0075) —
+  so prefer not to write one: scoped auth rules declare their contribution by
+  performing it, and `createScopedImplement<AuthScopes<typeof hook>>()` derives
+  the map from the hook
+  ([details](./auth-and-errors.md#scoped-rules--the-map-createscopedimplement-consumes),
+  → ADR 0078).
 - An endpoint hoisted out of the contract literal widens its `scope` to `string`,
   which is no key of any map, and lands in the error branch. An endpoint whose
   `scope` is added by a conditional spread is optional, so it resolves to **both**
@@ -753,6 +758,14 @@ The same map has a registry form and a streaming form:
 const implementAll = createScopedImplementRegistry<Scopes>()
 export const services = implementAll(apiContractRegistry, { posts, users })
 
+// a service FILE declares its handlers typed but unbound — binding happens
+// once, in the registry. Curried out of necessity: one call cannot both take
+// the contract and contextually infer the handlers from it.
+export const posts = implementFor.declare(postsContract)({
+  list: (ctx) => listPosts(ctx.userId),          // ctx typed per endpoint scope
+  purge: (ctx) => (ctx.isAdmin ? purge() : []),
+})
+
 // a streaming multipart handler that reads its scope's fields. The endpoint
 // must declare its own `scope`, and only that literal is accepted: an endpoint
 // inheriting the contract's scope cannot be verified from here, and guessing it
@@ -785,9 +798,22 @@ export const apiServices = implementRegistry(apiContractRegistry, {
 
 Every registry key is required, extra keys fail, and each handler map is checked
 against its own contract. The returned service order follows the contract
-registry order. `createImplementRegistry<AppContext>()` fixes the application
+registry order — and the same services ride along under `.byKey`, so a consumer
+whose registry keys are load-bearing (filtering a tool surface per caller) never
+rebuilds a prefix lookup by hand:
+
+```ts
+const services = implementRegistry(apiContractRegistry, handlers)
+createServer({ services })                       // the array, as before
+const visible = [services.byKey.users]           // the same objects, by key
+```
+
+`createImplementRegistry<AppContext>()` fixes the application
 context once, like `createImplement` does for a single contract. Runtime callers
-also fail first on missing/extra keys and duplicate contract prefixes.
+also fail first on missing/extra keys and on a duplicate prefix **within one
+scope** — the same prefix under two different group scopes is legal (their URLs
+are separated by `scopePrefixes`, and a genuine path clash is the router's own
+construction error).
 
 The registry is intentionally flat: every key must point to one concrete
 `defineContract()` result. Composed namespace arrays are mounted explicitly with
@@ -3755,7 +3781,61 @@ endpoints under the group declare `scope: 'tenant'`.
 | `onForbidden` | thrown when an identity is present but the rule rejects it (default 403) |
 
 Annotate `rules` with `satisfies Record<MyScope, AuthRule<User>>` so the compiler
-catches a scope you forgot to cover.
+catches a scope you forgot to cover. With the scoped rule objects below, widen
+the annotation to
+`satisfies Record<MyScope, AuthRule<User> | ScopedAuthRule<User, object>>` — it
+keeps the coverage check and does not disturb the derivation. (When every scope
+comes from the derived map, the check is already implicit: a scope missing from
+`rules` is no key of the map, and a contract using it fails to compile.)
+
+### Scoped rules — the map `createScopedImplement` consumes
+
+A rule may take an object form, `{ rule, inject }`, where `inject` **returns**
+the fields this scope contributes. That return type is a declaration the hook
+derives a scope→context map from — feed it to
+[`createScopedImplement`](./server.md#per-scope-handler-context--createscopedimplement)
+and the map can never drift from the hook, because it is computed from it:
+
+```ts
+const authHook = createAuthHook({
+  resolve: sessionResolver,             // no explicit generic — let it infer
+  rules: {
+    public: { rule: 'public', inject: (user) => ({ userId: user.id }) },
+    user: { rule: 'authenticated', inject: (user) => ({ userId: user.id }) },
+    admin: {
+      rule: (user) => user.admin,
+      inject: (user) => ({ userId: user.id, isAdmin: user.admin }),
+    },
+  },
+})
+
+export const implementFor = createScopedImplement<AuthScopes<typeof authHook>>()
+```
+
+- A `'public'` rule's fields come out **optional**: public admits the anonymous
+  caller, it does not refuse to know the logged-in one — `resolve` and `inject`
+  still run, so a public `me` / `logout` handler reads `ctx.userId` as
+  `string | undefined` and narrows, instead of being pushed toward a cast by a
+  `public: object` map.
+- Any other rule's fields are required — the rule rejected the request before
+  the handler if no identity resolved.
+- A scope with no rule is no key of the derived map, so a contract using it
+  fails to compile — the type-level mirror of the hook's fail-closed
+  `no rule for scope` throw.
+
+The per-rule `inject` runs after the shared one, only when an identity
+resolved, and **before** the rule check — it may run for an identity the rule
+then rejects, so keep it pure and synchronous (an async `inject` is a compile
+error, and a runtime one for untyped callers: merging a Promise would merge
+nothing). Write rule objects inline in `rules` — a hoisted, annotated rule
+widens its inject and degrades that scope's fields to `object`.
+
+Derivation needs the identity generic to be **inferred** (write no explicit
+`createAuthHook<User>` — TypeScript has no partial inference); with an explicit
+generic, or fields injected outside the hook, keep the hand-written map. Two
+hooks guarding different scopes compose by intersection:
+`createScopedImplement<AuthScopes<typeof userHook> & AuthScopes<typeof botHook>>()`.
+→ ADR 0078
 
 ### Auth on the tool surface — `resolveFromContext`
 
@@ -4797,6 +4877,71 @@ closing one whose chain is already running leaves that chain to finish and keeps
 the handle claimed, since a second binding could not force it. `promise` is
 already observed internally, so ignoring it never raises an `unhandledRejection`.
 
+#### Composite shutdown target — parallel domain drains
+
+`bindProcessSignals` takes `Pick<ManagedServerHandle, 'shutdown'>` — an
+**interface**, not the server. An application whose shutdown spans several
+domains (transport, bots, agent runs, broadcasts) composes them into one target;
+the signal machine stays the framework's, the composition stays yours:
+
+```ts
+const composite: ShutdownTarget = {
+  async shutdown(options?: ShutdownOptions): Promise<ShutdownResult> {
+    const { signal } = ShutdownOptionsSchema.parse(options ?? {})
+    // Domain drains run in parallel with the transport drain, all watching the
+    // same force signal the second OS signal aborts.
+    const [transport, bots, agents, broadcasts] = await Promise.all([
+      server.shutdown(options),
+      drainBots(signal),
+      drainAgents(signal),
+      drainBroadcasts(signal),
+    ])
+    return {
+      ...transport,
+      // Fold domain leftovers into the transport result so `onComplete` sees
+      // one honest outcome.
+      outcome: transport.outcome === 'clean' && bots + agents + broadcasts === 0
+        ? 'clean'
+        : 'forced',
+    }
+  },
+}
+
+bindProcessSignals(composite, { shutdown: { gracePeriodMs: 30_000 } })
+```
+
+The transport half inside stays the real managed handle — its admission gate and
+HTTP drain are not reimplemented, only composed. Domain drains must watch the
+`signal` themselves: it is the only channel a second OS signal has into a
+running chain.
+
+#### The last line of defence is yours
+
+The framework never calls `process.exit`, and `process.exitCode` only takes
+effect once the event loop empties — which is exactly what a stuck resource
+prevents. If the deployment must exit before the supervisor's `SIGKILL`, arm an
+application-side timer:
+
+```ts
+onShutdown: () => {
+  setTimeout(() => process.exit(1), 60_000).unref()
+},
+```
+
+`unref()` keeps the timer from holding a healthy process open; it only fires if
+something else already is.
+
+#### When NOT to use `bindProcessSignals`
+
+- The application already runs a signal machine with states this one does not
+  have (staged escalation policies, per-signal semantics beyond
+  first/force/escalate). Two machines on the same signals is worse than either.
+- Signal policy must differ per signal (e.g. `SIGHUP` = reload, not shutdown) —
+  bind only the terminating signals here and keep the rest yours.
+- Something else in the process must keep listening for the same signal: the
+  escalation path restores the default disposition only when nothing else
+  listens, and reports `onEscalationBlocked` otherwise.
+
 The server owns HTTP/Socket.IO transport resources. MCP, databases, queues and
 domain run-state remain application resources and close explicitly after server
 drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
@@ -6217,7 +6362,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
 | `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
 | `createImplement` | function | fix the handler context type once |
-| `createScopedImplement` | function | fix one scope→context map, then type every handler by its endpoint's effective scope — [guide](../guide/server.md#per-scope-handler-context--createscopedimplement) |
+| `createScopedImplement` | function | fix one scope→context map, then type every handler by its endpoint's effective scope; `.declare(contract)(handlers)` types without binding for the registry path, `.stream(scope, …)` covers streaming multipart — [guide](../guide/server.md#per-scope-handler-context--createscopedimplement) |
 | `ScopedHandlers` | _type_ | handler map typed per endpoint by its effective scope |
 | `ScopeContexts` | _type_ | scope → extra context fields map accepted by `createScopedImplement` |
 | `EffectiveScope` | _type_ | an endpoint's own `scope`, else its contract's group scope |
@@ -6229,6 +6374,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
 | `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
 | `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `KeyedServices` | _type_ | registry result: the mount-ordered `ServiceDef[]` carrying the same services under `.byKey` |
 | `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
 | `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
 | `staticRoute` | function | a raw route that serves a directory |
@@ -6290,6 +6436,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `AuthHook` | _type_ | the hook `createAuthHook` returns |
 | `AuthHookConfig` | _type_ | config for `createAuthHook` |
 | `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `ScopedAuthRule` | _type_ | a rule plus its typed context contribution — `{ rule, inject? }` |
+| `AuthRules` | _type_ | the `rules` map: bare rules or scoped rules |
+| `RuleScopes` | _type_ | scope→context map derived from a `rules` object; `'public'` fields become optional |
+| `ScopedAuthHook` | _type_ | an auth hook carrying its derived scope map at the type level |
+| `AuthScopes` | _type_ | recover the derived map — `createScopedImplement<AuthScopes<typeof hook>>()` |
 | `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
 | `JwtPayload` | _type_ | a decoded JWT payload |
 | `SignJwtOptions` | _type_ | options for `signJwt` (expiry, claims) |
@@ -6352,7 +6503,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'shutdown' \| 'complete'` — which phase an `onError` report came from |
 | `SignalSource` | _type_ | injectable signal source — `process` by default |
 | `ProcessSignalName` | _type_ | signal names the binding accepts (owned, so the published types need no `@types/node`) |
-| `ShutdownTarget` | _type_ | the `shutdown`-only slice of a managed handle a binding needs |
+| `ShutdownTarget` | _type_ | the `shutdown`-only slice a binding needs — an interface, so a [composite target](../guide/testing-and-deployment.md#composite-shutdown-target--parallel-domain-drains) can drain several domains under one signal machine |
 | `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 |
@@ -6481,6 +6632,7 @@ payload.
 | `resolveMedia` | function | resolve a media reference for a tool result |
 | `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
 | `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
+| `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
 | `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
 | `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
 | `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.50.0",
+  "version": "0.52.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",

package/dist/index-r1qp4rve.js

@@ -1,57 +0,0 @@
-// src/server/middleware/cors.ts
-var DEFAULT_CORS_ALLOW_HEADERS = "Content-Type, Authorization, X-Trace-Id, traceparent, tracestate";
-var DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Request-Id";
-function assertCorsConfig(config) {
-  if (config.credentials && (config.origin === undefined || config.origin === "*")) {
-    throw new Error("[stitchkit] cors: `credentials: true` cannot be combined with a wildcard origin. " + "Set `origin` to an explicit string or list.");
-  }
-  if (config.origin === undefined) {
-    throw new Error("[stitchkit] cors: `origin` is required. Pass an explicit origin (or list), or '*' to deliberately allow every origin — omit `cors` entirely to emit no CORS headers.");
-  }
-  if (Array.isArray(config.origin) && config.origin.length === 0) {
-    throw new Error("[stitchkit] cors: `origin` cannot be an empty list. Pass explicit origins, or '*' to deliberately allow every origin.");
-  }
-}
-function resolveOrigin(config, requestOrigin) {
-  if (config.origin === undefined)
-    return;
-  if (config.origin === "*") {
-    return "*";
-  }
-  if (Array.isArray(config.origin)) {
-    if (!requestOrigin)
-      return;
-    const lower = requestOrigin.toLowerCase();
-    return config.origin.some((o) => o.toLowerCase() === lower) ? requestOrigin : undefined;
-  }
-  return config.origin;
-}
-function corsHeaders(config, requestOrigin) {
-  const allowOrigin = resolveOrigin(config, requestOrigin);
-  const headers = {
-    "Access-Control-Allow-Methods": config.methods ?? "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": config.headers ?? DEFAULT_CORS_ALLOW_HEADERS
-  };
-  const expose = Array.isArray(config.exposeHeaders) ? config.exposeHeaders.join(", ") : config.exposeHeaders ?? DEFAULT_CORS_EXPOSE_HEADERS;
-  if (expose !== "") {
-    headers["Access-Control-Expose-Headers"] = expose;
-  }
-  if (allowOrigin !== undefined) {
-    headers["Access-Control-Allow-Origin"] = allowOrigin;
-    if (config.credentials) {
-      headers["Access-Control-Allow-Credentials"] = "true";
-    }
-  }
-  if (Array.isArray(config.origin)) {
-    headers.Vary = "Origin";
-  }
-  return headers;
-}
-function corsPreflightResponse(config, req) {
-  return new Response(null, {
-    status: 204,
-    headers: corsHeaders(config, req.headers.get("origin"))
-  });
-}
-
-export { DEFAULT_CORS_ALLOW_HEADERS, DEFAULT_CORS_EXPOSE_HEADERS, assertCorsConfig, corsHeaders, corsPreflightResponse };