@nifrajs/cli 2.11.0 → 2.12.0

package/docs/llms-full.txt

@@ -596,6 +596,23 @@ await api.search.get({ query: { page: "3" } })              // query string
 await api.users({ id: "1" }).posts({ postId: "2" }).get()   // nested params
 ```
 
+**Reserved proxy keys.** The client proxy resolves a fixed set of property names
+_before_ path segments: the seven HTTP verbs
+(`get`/`post`/`put`/`patch`/`delete`/
+`head`/`options`, any casing) call the route, and
+`subscribe`, `ws`, `index`, and `then` (exact
+match) are the SSE, WebSocket, root-path, and thenable-guard keys. A route whose path
+contains a static segment spelling one of these - `.post("/api/delete", …)` -
+cannot be reached by **dot access**: `api.delete.post` resolves the
+`delete` verb, not the segment. The typed spelling is a **call on the parent
+node** - `api.api("delete").post()` sends `POST /api/delete` - the
+same call params use, accepting exactly the colliding segment names. The client type rejects
+the dot access at compile time with that guidance, and `nifra check` reports the
+collision (`NF-C018`, advisory). Prefer a verb-free segment
+(e.g. `/api/remove`) when you control the path; mark a route served only to
+non-typed-client consumers with `// nifra-expect reserved-segment` above its
+registration.
+
 ### Results never throw
 
 Every call resolves to a discriminated `Result`: branch on `ok` (or
@@ -1743,6 +1760,12 @@ does custom, typed verification.
 `cacheControl()` sets `Cache-Control` on matching responses without
 clobbering one a handler already set.
 
+**Security note (BREACH):** any HTTP compression makes the response size depend on its
+content, so a response that mixes a secret with attacker-reflected request input can leak
+the secret through the compressed length. Nifra's CSRF tokens are HMAC-signed per session
+and safe to compress, but if a route reflects request input alongside a per-request secret,
+exclude it via the `compressible` option or route scoping.
+
 ```ts
 import { server } from "@nifrajs/core/server"
 import { compression, cacheControl } from "@nifrajs/middleware"
@@ -1894,12 +1917,13 @@ createWebApp({
 
 ## Nifra - security & hardening
 
-> Bounded request bodies, magic-byte file-upload validation, constant-time webhook verification, and idempotency-key replay - the hardening primitives every production app needs, built in.
+> Bounded request bodies, JSON prototype-poisoning defense, magic-byte file-upload validation, constant-time webhook verification, security response headers, and idempotency-key replay - the hardening primitives every production app needs, built in.
 
 The pieces every production endpoint needs - a body-size cap for raw routes, real file-type
 validation, constant-time webhook verification, and idempotent retries - ship as first-party
 primitives. All are **edge-safe** (WebCrypto, no `node:crypto`) and run unchanged
-on Bun, Node, Deno, and Workers.
+on Bun, Node, Deno, and Workers. For how these defaults stack up against Hono, Fastify,
+Express, and Elysia, see [security posture, compared](/docs/security-comparison).
 
 ### Responses that cannot leak more than they declare
 
@@ -1992,6 +2016,65 @@ bad JSON a `400` - thrown as control-flow `Response`s the lifecycle catches,
 so the cap can't be silently skipped. Pass a larger `maxBytes` for an upload route, a
 smaller one to tighten an endpoint.
 
+The cap is enforced on the bytes actually **delivered**, never on the number the caller wrote in
+`Content-Length`. That distinction is the whole defense: an adapter that rebuilds a
+request from an event envelope, or any code assembling a `Request` by hand, can carry a
+header claiming 5 bytes over a payload of five megabytes. A runtime HTTP parser cannot lie that way,
+because it framed the body at the declared length itself, so nifra's ingress adapters mark their
+requests as runtime-framed and skip the recount entirely:
+`listen()` on Bun, `toFetchHandler(app)` on Workers and edge,
+`@nifrajs/deno`, and `@nifrajs/node` (which reads exact byte counts in the
+first place). Nothing to configure on any of them.
+
+Only a request arriving through a path nifra ships no adapter for pays the extra pass over the body.
+If you serve an edge runtime by exporting the app directly rather than through
+`toFetchHandler`, `server({ trustBodyFraming: true })` asserts that every
+`app.fetch` request came from the platform's own parser. It is an assertion about
+deployment topology, so do not set it on an app whose `fetch` is also called with
+requests built from untrusted input. It trusts the _frame_, never the cap: an over-cap declared
+length is still a `413`, and a body with no `Content-Length` still goes
+through the streaming guard.
+
+### Prototype-poisoning defense
+
+Every JSON body nifra parses - the schema-validated route and `c.boundedJson`
+alike - is screened for the prototype-pollution shape: an own `__proto__` key, or
+a `constructor` whose value carries a `prototype`. `JSON.parse`
+creates these as ordinary data properties, and the damage lands later, when innocent code does
+`{ ...body }`, `Object.assign(target, body)`, or a deep merge and
+walks that key onto a real prototype. The screen is on by default.
+
+```ts
+import { server } from "@nifrajs/core/server"
+
+// Default is "reject". A JSON body with an own `__proto__` key - or a `constructor`
+// carrying a `prototype` - is the exact shape that turns a later innocent { ...body }
+// merge or Object.assign into prototype pollution. It answers the SAME flat 400 as
+// malformed JSON, so an attacker learns nothing from the response.
+const app = server({ protoPoisoning: "reject" }) // "strip" | "ignore" also available
+
+app.post("/profile", async (c) => {
+  const body = await c.boundedJson<{ name: string }>() // and the schema-route path
+  // Reached only for a clean payload. Under "strip" the offending keys are deleted and
+  // the handler sees the cleaned object; under "ignore" the body passes through as-is.
+  return { name: body.name }
+})
+```
+
+`protoPoisoning` is a server option with three settings.
+` "reject"` (the default) answers the same flat `400` as
+malformed JSON - indistinguishable on the wire, so a probe learns nothing.
+`"strip"` deletes the offending keys and hands the handler the cleaned
+value, siblings intact. `"ignore"` parses as-is, for a route you are sure
+never merges body input into another object. A string _value_ of `"__proto__"`
+is legal data and never triggers - only an own key of that name does.
+
+The check is sound against escape smuggling: a `__proto__`-spelled key
+parses to the same own property, so it is caught the same way. And it is cheap on the common
+path - a clean body pays a substring pre-scan only; the deep walk runs solely when the raw text
+actually contains a suspect token, so an honest payload is never charged for the tree it does
+not have.
+
 ### File uploads - `@nifrajs/uploads`
 
 A dependency-free package for the upload-hardening basics. `validateUpload` enforces a
@@ -2171,6 +2254,37 @@ trustworthy client IP can be derived, and never trusts `X-Forwarded-For` unless
 bodies before routing (fails closed with `411` on a length-less body). The read-time
 guard above (`c.boundedBody` / schema cap) remains the source of truth.
 
+### Security response headers - `securityHeaders`
+
+`securityHeaders()` sets a safe-by-default response header set on every response,
+errors and 404s included. Three are always on - `X-Content-Type-Options: nosniff`,
+`X-Frame-Options: DENY`, and `Referrer-Policy: no-referrer`. The
+cross-origin isolation headers (`COOP`/`COEP`/`CORP`),
+`Permissions-Policy`, `Content-Security-Policy`, and `HSTS` are
+opt-in, because each one can break a working app (embedding, popups, HTTP) and so is a
+deliberate choice, never a silent default.
+
+```ts
+import { server } from "@nifrajs/core/server"
+import { securityHeaders } from "@nifrajs/middleware"
+
+// Always on (covering errors and 404s too): X-Content-Type-Options: nosniff,
+// X-Frame-Options: DENY, Referrer-Policy: no-referrer. The rest are opt-in - each is a
+// deliberate cross-origin decision, so nifra never turns them on behind your back:
+const app = server().use(securityHeaders({
+  crossOriginOpenerPolicy: "same-origin",      // isolate the browsing-context group
+  crossOriginResourcePolicy: "same-origin",    // block cross-origin embedding of your responses
+  crossOriginEmbedderPolicy: "require-corp",   // enable crossOriginIsolated (SharedArrayBuffer, …)
+  permissionsPolicy: "camera=(), geolocation=()",
+  contentSecurityPolicy: "default-src 'self'",
+  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true }, // opt in once HTTPS-only
+}))
+```
+
+Every value is fixed at construction, so the headers are declared statically rather than
+written by a response hook - an app whose response middleware is only this keeps the fused
+native response lanes. A route that sets one of these names itself keeps its own value.
+
 ### Route assurance - prove every route is guarded
 
 Installing security middleware is not the same as proving it covers every route. Nifra&apos;s
@@ -2313,8 +2427,11 @@ const sagas = createSagaEngine({
 ### Already built in
 
 These add to Nifra's standing defaults: strict-by-default schema validation (unknown fields
-rejected), SSR serialization that escapes every inline-script value, signed-cookie sessions + CSRF
-+ route guards ([@nifrajs/auth](/docs/auth)), bearer/apiKey auth + a shared-store rate
+rejected), SSR serialization that escapes every inline-script value,
+`__Host-`/`__Secure-` cookie-prefix enforcement (a cookie whose
+attributes violate its prefix contract fails at serialization rather than being silently
+dropped by the browser), signed-cookie sessions + CSRF + route guards
+([@nifrajs/auth](/docs/auth)), bearer/apiKey auth + a shared-store rate
 limiter ([@nifrajs/middleware](/docs/plugins)), and a hardened image-resize endpoint
 ([@nifrajs/image/server](/docs/images)).
 
@@ -3004,10 +3121,13 @@ you bring JSON catalogs.
 
 ### Negotiate the locale
 
-`negotiateLocale` picks the best supported locale from a cookie (an explicit choice),
-then `Accept-Language` (quality-ranked, with `fr-CA`→`fr`
-base-subtag fallback), else your default. Resolve it in a loader and return just that locale's
-messages.
+`negotiateLocale` picks the best supported locale from a `?lang=` query
+parameter (an explicit ask), then a cookie (a remembered choice), then
+` Accept-Language` (quality-ranked, with `fr-CA`→`fr`
+base-subtag fallback), else your default. The answer is always drawn from your
+` locales` allow-list - request input is matched, never echoed - so a hostile
+` ?lang=` can't reach the response. Resolve it in a loader and return just that
+locale's messages.
 
 ```ts
 // In a loader: resolve the locale + return only that catalog's messages.
@@ -3015,12 +3135,34 @@ import { negotiateLocale } from "@nifrajs/i18n"
 import { catalogs, locales } from "../catalogs"
 
 export async function loader({ request }: { request: Request }) {
-  const q = new URL(request.url).searchParams.get("lang")
-  const locale = q && locales.includes(q) ? q : negotiateLocale(request, { locales, defaultLocale: "en", cookie: "lang" })
-  return { locale, messages: catalogs[locale] }   // cookie → Accept-Language → default
+  const locale = negotiateLocale(request, { locales, defaultLocale: "en", queryParam: "lang", cookie: "lang" })
+  return { locale, messages: catalogs[locale] }   // ?lang= → cookie → Accept-Language → default
 }
 ```
 
+On the server, `localeDetector()` (from `@nifrajs/i18n/detector`, needs
+` @nifrajs/core`) wraps the same negotiation as a plugin: handlers read
+` c.locale`/`c.localeSource`, responses carry
+` Content-Language`. With `persist: true` it writes the locale cookie
+** only** when an explicit `?lang=` choice differs from the cookie - a
+header-derived guess is never pinned, and plain requests never grow a
+`Set-Cookie`, so responses stay cacheable. (`@nifrajs/middleware`'s
+` language()` is the header-only sibling; use one or the other.)
+
+```ts
+// Or as a server plugin: c.locale on every handler, Content-Language on every response.
+import { server } from "@nifrajs/core"
+import { localeDetector } from "@nifrajs/i18n/detector"
+
+const app = server().use(localeDetector({
+  locales: ["en", "fr", "de"],
+  defaultLocale: "en",
+  queryParam: "lang",
+  cookie: "locale",
+  persist: true,        // pin an explicit ?lang= choice into the cookie
+})).get("/", (c) => c.json({ locale: c.locale, via: c.localeSource }))
+```
+
 ### Format messages
 
 `createFormatter(locale, messages)` → `{ t, n, d }`. `t`
@@ -3108,6 +3250,14 @@ export default { fetch: (req: Request, env: Env, ctx: ExecutionContext) =>
   app.fetch(req, { env, waitUntil: ctx.waitUntil.bind(ctx) }) }
 ```
 
+Export through `toFetchHandler` rather than handing the app out directly. Besides
+`env` and `ctx.waitUntil`, it tells nifra the request came from the
+platform's own HTTP parser, which lets the
+[bounded-body cap](/docs/security) trust the declared
+`Content-Length` as a real transport frame instead of re-counting every JSON body.
+A bare `export default app` has no such signal and pays the extra pass unless you
+set `server({ trustBodyFraming: true })`.
+
 ### Background work
 
 `c.waitUntil(promise)` keeps work alive after the response is sent - cache writes,
@@ -3511,6 +3661,30 @@ content-typed, with an immutable cache - before the app runs, leaving the SSR fa
 untouched: `serve(app, {'{ port, static: { dir: new URL("./assets/", import.meta.url) } }'})`.
 On Cloudflare/Vercel the platform serves assets, so you don't need it there.
 
+### AWS Lambda
+
+`@nifrajs/aws-lambda` - API Gateway HTTP APIs (payload v2) and Lambda Function
+URLs. `handle(app)` is the buffered handler; `streamHandle(app)`
+streams responses on Function URLs with `InvokeMode: RESPONSE_STREAM`. Build the
+app at module scope (once per container). The adapter decodes the body and checks its real
+size before a `Request` exists, assembles headers + the v2 `cookies`
+array in one place, decides response base64 by what the bytes actually are, and feeds
+`sourceIp` into `c.clientIp`. `waitUntil` work settles
+before the container freezes. REST APIs (payload v1) and ALB are not supported.
+
+```ts
+// handler.ts - one app per container, built at module scope
+import { handle, streamHandle, type LambdaEnv } from "@nifrajs/aws-lambda"
+import { server } from "@nifrajs/core"
+
+const app = server<LambdaEnv>()
+  .get("/", (c) => c.json({ ip: c.clientIp, requestId: c.env.context?.awsRequestId }))
+
+export const handler = handle(app) // API Gateway HTTP API (v2) + Function URLs
+// or, on a Function URL with InvokeMode: RESPONSE_STREAM:
+// export const handler = streamHandle(app)
+```
+
 ### Cloudflare Workers / Pages (the edge)
 
 `buildServer` bundles with edge conditions (`workerd`,
@@ -5557,7 +5731,9 @@ const app = server().merge(createBillingRouter({ charge: async (plan) => ({ id:
 // 4. Build the client from the EXPORTED contract value - decoupled, no `typeof app` import needed.
 const api = client(billingContract, "https://api.example.com")
 const { data } = await api.billing.plan.get()          // GET  /billing/plan
-await api.billing.subscribe.post({ plan: "pro" })      // POST /billing/subscribe, body typed
+// "subscribe" is a reserved client word (the SSE subscriber), so this segment is reached by
+// CALLING the parent node with the segment name - same request, same typed body.
+await api.billing("subscribe").post({ plan: "pro" })   // POST /billing/subscribe, body typed
 ```
 
 Why this survives `.d.ts` emit where the fluent chain doesn't: the contract is a
@@ -6455,6 +6631,488 @@ backend you can also ship on its own. Start with [Getting started](/docs).
 Moving a backend (Express, Hono, Fastify, Elysia) instead? See
 [Migrating a backend](/docs/migrate-backend).
 
+## Nifra - Migrate route by route
+
+> Keep an existing Hono, Elysia, Express, or Workers app running while moving routes into typed Nifra handlers one at a time.
+
+Keep the old app live while you move its surface into Nifra. Mount the legacy fetch handler at
+a prefix, add typed Nifra routes as they are ready, then delete the mount when the prefix is
+empty.
+
+[!WARNING] Mounted handlers are an escape hatch. Their request and response shapes are outside
+Nifra's typed route contract, response schemas, and response-contract enforcement. Keep the
+mount small and temporary, and use typed routes for every migrated endpoint.
+
+### 1. Mount the existing app
+
+`mountFetch` accepts any handler with the Web fetch shape. Use a path ending in
+`/*` for a subtree. By default the legacy app sees the original URL. Set
+`stripPrefix: true` when the legacy app declares paths relative to its mount point.
+The platform object is forwarded as the second argument when the runtime supplies one.
+
+```ts
+import { Hono } from "hono"
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+const legacy = new Hono()
+legacy.get("/users", (c) => c.json({ source: "hono", users: [] }))
+legacy.post("/users", async (c) => c.json(await c.req.json()))
+
+export const app = server()
+  // The wildcard is a literal mount prefix, not a typed Nifra route.
+  .mountFetch("/legacy/*", legacy.fetch, { stripPrefix: true })
+  // Typed routes take precedence, so move one route out of Hono at a time.
+  .get("/legacy/users/:id", (c) => ({ id: c.params.id, source: "nifra" }))
+  .post(
+    "/users",
+    { body: t.object({ name: t.string() }) },
+    (c) => ({ id: crypto.randomUUID(), name: c.body.name }),
+  )
+```
+
+### 2. Move the routes
+
+- Choose one legacy endpoint and add it as a typed Nifra route.
+
+- Keep the mount in place for the remaining endpoints.
+
+- Add a body, query, or params schema so the trust boundary is explicit.
+
+- Run `nifra check` and the route tests, then repeat.
+
+Typed routes win when both surfaces match. That lets a new Nifra route replace its legacy
+counterpart without changing the mount prefix or adding a second server.
+
+### 3. Remove the escape hatch
+
+When the legacy prefix has no remaining routes, remove `mountFetch` and delete the
+old app. The remaining routes now have typed params, validated inputs, reflected contracts,
+and the end-to-end typed client.
+
+### Other legacy handlers
+
+The same seam works with Elysia, an Express app exposed through an adapter, or a raw Workers
+handler. Pass its fetch-compatible function directly. For a Workers-style handler, the
+platform argument carries bindings and `waitUntil`; mounted code remains responsible
+for its own framework-specific request and response conventions.
+
+## Nifra security posture vs Hono, Fastify, Express, Elysia
+
+> A dimension-by-dimension security comparison of Nifra against the current releases of Hono, Fastify, Express, and Elysia - which hardening each framework ships by default, which is opt-in, and which is left to third-party packages.
+
+Which hardening each framework actually ships. A dimension-by-dimension read of Nifra&rsquo;s
+security defaults against the **current releases** of Hono, Fastify, Express, and Elysia -
+what is on by default, what is opt-in, and what is left to a third-party package. For how each
+Nifra primitive works, see [Security & hardening](/docs/security).
+
+### The honest verdict
+
+Nifra is **at or above parity on every dimension where a comparison is meaningful**, and
+ahead of all four on several:
+
+-
+**Ahead of all four:** CORS misconfiguration resistance, redirect safety, WebSocket
+origin policy, rate-limiter safe-by-construction design, route-level security evidence
+(`nifra assure`), response over-exposure enforcement, upload content
+verification, env-independent error responses, client-IP trust model.
+
+-
+**Par with the best-in-class:** body limits (Fastify class), JSON prototype-poisoning
+rejection (par Fastify, default-on), schema validation (par Fastify/Elysia), CSRF (par
+Fastify), security headers (par Hono, first-party), cookie prefixes (par Hono), sessions,
+JWT hardening, static serving, supply chain (par Hono&rsquo;s zero-dependency core).
+
+**One caveat no capability table removes.** Hono, Fastify, and Express have orders of
+magnitude more production exposure and more external researchers looking at them. Nifra&rsquo;s
+protections are implementation-verified and unit-tested, but have not had that volume of
+adversarial attention or a third-party audit. Ongoing scrutiny is the part only time buys.
+
+### How this was measured
+
+Nifra side: an implementation-level read of every security-relevant module across
+`core`, `middleware`, `auth`, `node`,
+`web`, `uploads`, and `cli` - defaults and failure modes, not
+marketing claims. Competitor side: current official documentation for defaults, verified as of
+August 2026 against Hono 4.12.x, Fastify 5.x, Express 5.1 / 4.21.x, and Elysia 1.4.x. The
+comparison unit is what a developer gets **by default** and what the framework makes
+**impossible to get wrong**, not what a maximally careful expert could configure - because
+most real-world security incidents are misconfiguration-by-default.
+
+### Summary matrix
+
+Legend: **B** built-in and on by default, **b** built-in opt-in, **O** official
+add-on package, **3** third-party / community, **-** absent. The verdict column is Nifra
+relative to the field.
+
+Dimension
+Nifra
+Hono
+Fastify
+Express
+Elysia
+Verdict
+
+Default body-size cap
+B 1 MB
+- (opt-in mw)
+B 1 MiB
+- (needs body-parser)
+- (runtime cap only)
+par Fastify; ahead of the rest
+
+Bounded streaming reads
+B
+b
+B
+O
+-
+par-plus
+
+Body cap on delivered bytes (not the claimed length)
+B
+- (keys on Content-Length)
+b
+-
+-
+ahead
+
+Proto-pollution-inert parsers (query / cookie / form / params)
+B null-proto
+B
+B
+B (5.x simple parser)
+B
+par
+
+JSON proto-key rejection
+B (reject default)
+-
+B (proto + constructor)
+-
+b (schema-strip)
+par Fastify
+
+Route ReDoS surface
+B none (strict grammar)
+B
+B (find-my-way)
+B (path-to-regexp)
+B
+par
+
+Input schema validation
+B per-route Standard Schema
+b (validator mw)
+B ajv
+-
+B TypeBox
+par with best
+
+Response over-exposure prevention
+B contract warn/enforce
+-
+b (serializer)
+-
+B normalize
+ahead (with Elysia)
+
+Error responses leak-free by construction
+B env-independent flat 500
+B
+B (mostly)
+b (dev leaks stacks)
+B (mostly)
+ahead
+
+CORS safe-by-construction
+B fail-loud ctor
+b (reflect-with-creds configurable)
+O
+O
+O
+ahead
+
+CSRF
+B two layers (origin + signed double-submit)
+b (origin heuristic)
+O token-based
+3 (csurf deprecated)
+-
+ahead; par Fastify
+
+Security headers (first-party)
+b (nosniff/XFO/RP on; COOP/COEP/CORP/PP/CSP/HSTS opt-in)
+b (broader default set once added)
+O helmet
+3 helmet
+3
+par Hono; ahead of the helmet-dependent ones
+
+Cookie signing + safe serialization
+B
+b
+O
+O
+B
+par-plus
+
+`__Host-`/`__Secure-` prefix enforcement
+
+B (throws on violation)
+B (throws on violation)
+O
+O
+-
+par Hono
+
+Sessions (HttpOnly, SameSite, fixation, fail-closed)
+B
+-
+O
+3 (express-session)
+3
+ahead
+
+JWT hardening (alg allowlist, none-reject, exp required)
+B
+b (no allowlist, exp optional)
+O (fast-jwt)
+3
+O (jose)
+par-plus
+
+Rate limiting
+B forced-decision ctor
+3
+O
+3
+3
+ahead
+
+Client IP / proxy trust
+B explicit, fail-closed
+b (per-runtime helpers)
+B (trustProxy)
+B (manual trust proxy)
+-
+ahead
+
+Reverse-proxy hop-by-hop hygiene
+B (strips both directions)
+b (proxy helper)
+O (http-proxy)
+3
+-
+ahead
+
+Load shedding / overload
+B admission (in-flight + loop lag)
+-
+O under-pressure
+-
+-
+ahead; par Fastify
+
+Static serving traversal defense
+B 7-layer + dotfile deny
+3
+O (send-based)
+O (send-based)
+O
+ahead
+
+Redirect safety (open-redirect + CRLF)
+B same-origin default
+-
+-
+-
+-
+ahead (unique)
+
+WebSocket origin check
+B same-origin default
+-
+-
+-
+-
+ahead (unique)
+
+Upload content verification (magic bytes, EXIF strip)
+B package
+-
+O limits only
+3 (multer)
+b (t.File type/size)
+ahead
+
+Constant-time webhook verification
+B (multi-key rotation)
+-
+-
+-
+-
+ahead (unique)
+
+Idempotency-key replay
+B (atomic-claim store)
+-
+-
+-
+-
+ahead (unique)
+
+Supply chain (runtime deps in core)
+0
+0
+~dozen
+many
+few
+par with Hono
+
+Machine-checkable route security evidence
+
+B (`nifra assure`)
+
+-
+-
+-
+-
+unique
+
+Security lint (fail-open, non-constant-time, PII logs)
+B (NF-S001..007)
+-
+-
+-
+-
+unique
+
+### Dimension detail
+
+#### Body limits and bounded reads
+
+Nifra applies a 1 MB default cap to the schema lane and to
+`c.boundedBody`/`c.boundedJson`: an over-cap `Content-Length`
+is rejected before buffering (413), a malformed one is a 400, and a chunked or length-less
+body is drained through a true streaming byte counter that cancels at the cap. The cap is
+charged on the bytes actually **delivered**, never on the number a caller wrote in the
+header - so an adapter that rebuilds a request from an event envelope cannot smuggle a large
+payload behind a small declared length. Fastify enforces its 1 MiB default on real bytes and
+is the gold standard among the four; Nifra matches it. Hono&rsquo;s `bodyLimit` is
+an opt-in middleware that keys on `Content-Length`; Express relies on
+body-parser&rsquo;s 100 KB default only if you mount it; Elysia inherits the runtime cap
+(Bun&rsquo;s 128 MB).
+
+#### Prototype pollution
+
+Every hand-rolled parser (query, cookies, form, route params) produces null-prototype objects,
+so `__proto__`/`constructor` keys are inert there by construction. The
+JSON body lane **rejects** the poisoning shape by default - an own `__proto__`
+key, or a `constructor` carrying a `prototype` - answering the same flat
+400 as malformed JSON, with `"strip"` and `"ignore"`
+as alternatives. That matches Fastify, whose `onProtoPoisoning` and
+`onConstructorPoisoning` both default to `&apos;error&apos;`. Hono and
+Express do not reject proto keys in the JSON body; Elysia strips undeclared keys only on a
+validated route via its schema normalization.
+
+#### Validation and response contracts
+
+Nifra does per-route Standard Schema validation for body/query/params, and - the
+differentiating half - **response** schemas as an enforced upper bound:
+`"warn"` logs undeclared fields, `"enforce"` strips
+them. That kills the `passwordHash`-in-the-response class at the framework layer.
+Fastify offers the same protection through a declared response schema (opt-in); Elysia&rsquo;s
+exactMirror normalization strips undeclared response fields and is its strongest default.
+Hono&rsquo;s validator is opt-in with no response-side story, and Express ships nothing.
+
+#### CORS, CSRF, and error handling
+
+Nifra&rsquo;s `cors()` throws at construction when `credentials: true`
+meets `origin: "*"`, never reflects an origin by default with credentials,
+and lands headers on error responses too - it is **the only one of the five where the
+dangerous configuration is a construction-time error**. The other four leave
+reflect-with-credentials configurable. CSRF is two independent layers (Origin/Referer check
+plus a signed double-submit token, timing-safe); Hono&rsquo;s CSRF is an Origin /
+Sec-Fetch-Site heuristic, Fastify&rsquo;s official token package is comparable, Express&rsquo;s
+csurf is deprecated, and Elysia ships none in-tree. Uncaught errors become a flat 500
+unconditionally - not env-gated - so no configuration leaks a stack to the wire; Express&rsquo;s
+dev handler printing stacks when `NODE_ENV` is unset is the perennial
+counter-example.
+
+#### Headers, cookies, sessions, JWT
+
+Both Nifra and Hono ship a first-party security-headers middleware you add with
+`use()`. Nifra&rsquo;s turns on nosniff, `X-Frame-Options: DENY`, and
+`Referrer-Policy: no-referrer`, and keeps the headers that can break a working app
+(COOP/COEP/CORP, Permissions-Policy, CSP, HSTS) opt-in by design; Hono&rsquo;s covers a broader
+list on by default once added, HSTS included. Cookie serialization enforces RFC 6265 name
+tokens, caps at 4096 bytes, and enforces `__Host-`/`__Secure-` prefix
+preconditions at serialization time, throwing on a violation - the same behavior Hono&rsquo;s
+cookie helper has, and stricter than a silent browser drop. Sessions are always HMAC-signed,
+HttpOnly, SameSite=Lax, fail-closed, with `regenerate()` for fixation - no
+competitor ships sessions in-tree. JWT verification demands an algorithm allowlist, rejects
+`alg: none`, blocks algorithm confusion at the key level, and requires
+`exp` by default; Hono&rsquo;s JWT middleware takes a single required algorithm with
+no enforced allowlist and treats `exp` as optional, so Nifra is stricter there.
+
+#### Static serving, redirects, uploads, proxying
+
+Static serving runs seven layers - decode with 400 on malformed input, NUL rejection,
+segment-precise `..` rejection, backslash rejection, containment via
+`resolve`+`relative`, a `realpath` symlink re-check, and a
+default **dotfile deny** (a served `.env`/`.git` answers 404).
+`redirect()` requires a same-origin path by default and rejects CR/LF - Nifra is the
+only one of the five with a safe-by-default redirect. Uploads verify the real type by magic
+bytes and strip EXIF/GPS by re-encode, where the others do size limits at best.
+`@nifrajs/proxy` strips the RFC 9110 hop-by-hop set - plus every
+`Connection`-nominated header - in **both** directions by default.
+
+#### Rate limiting, IP trust, load shedding
+
+The rate limiter&rsquo;s constructor refuses to run until you choose a key source, so the
+&ldquo;trust proxy = spoofable keys&rdquo; footgun is a construction-time error;
+`X-Forwarded-For` is ignored at the default and counted from the right only when you
+declare trusted proxies. `c.clientIp` is the socket peer unless you pass an explicit
+trust config, and short chains fail closed. Admission sheds on live capacity evidence
+(in-flight count plus event-loop lag). Fastify&rsquo;s under-pressure is the only peer for load
+shedding; nothing else in the field forces the key decision or fails closed on IP trust.
+
+### Beyond parity - what none of the four ship
+
+-
+**Route assurance evidence.** Middleware publishes machine-checkable per-route claims
+(`AUTHENTICATED`, `BODY_BOUNDED`, `CSRF`,
+`RATE_LIMITED`, `IP_RESTRICTED`, `SECURITY_HEADERS`,
+`IDEMPOTENCY_KEY`), and `nifra assure` fails CI when a policy is unmet.
+Evidence is honest: an escape hatch suppresses its own claim.
+
+-
+**Security lint rules** - fail-open gate detection, non-constant-time secret comparison,
+sensitive values in log calls, and more, running in `nifra check`.
+
+-
+**Fail-loud constructors as a design norm** - CORS credentials+wildcard, rate-limit
+missing key decision, CSRF short secrets, in-memory stores in production - all
+construction-time errors, not runtime surprises.
+
+-
+**Response-contract enforce mode, admission load-shedding, idempotency keys, magic-byte +
+EXIF-strip uploads, and constant-time webhook verification** - each exists somewhere as a
+third-party add-on for the others; Nifra ships them first-party with assurance integration.
+
+### Where each alternative is still the right call
+
+This is a security read, not a blanket &ldquo;pick Nifra&rdquo;. Hono&rsquo;s run-anywhere
+minimalism and its zero-dependency core are genuinely excellent; Fastify&rsquo;s maturity,
+ecosystem, and years of adversarial attention are real advantages a young framework cannot
+claim; Express&rsquo;s ubiquity means every hire already knows it. Nifra&rsquo;s argument is
+narrower and honest: it makes the dangerous configurations _unrepresentable_, ships the
+hardening primitives first-party, and lets `nifra assure` prove in CI that every
+route is guarded. For the full capability and throughput comparison, see
+[vs other frameworks](/docs/comparison) and the
+[per-framework pages](/compare).
+
 ## Nifra - Contract-derived adversarial testing
 
 > Turn route schemas into hostile input, response-conformance, replay, shrinking, and runtime-matrix tests with @nifrajs/testing.
@@ -6837,6 +7495,33 @@ level that regressed comes back with the reason it broke.
 
 # Package reference (READMEs)
 
+## @nifrajs/agent
+
+Provider-neutral, typed, resumable agent turns over Nifra tool contracts.
+
+The package owns one bounded turn at a time. Model providers, state, approvals, budgets, idempotency,
+and telemetry are ports. The package never imports a model vendor and its state adapter stores only
+token-only turn evidence.
+
+```ts
+import { createAgentState, runAgent } from "@nifrajs/agent"
+
+const result = await runAgent(definition, { value: input }, ports, {
+  state: createAgentState("support-1"),
+  maxTurns: 8,
+})
+```
+
+The public in-memory adapters are for local development and tests. Durable state, provider
+credentials, and operated policy remain adapter concerns.
+
+Execution policies can be required by a tool contract. `createLocalProcessAdapter` applies cwd and
+environment filtering, timeouts, and cancellation to child processes. The local adapter is NOT a
+security boundary. Without OS-level sandboxing it contains crashes and accidents, not hostile code.
+
+For the compact agent contract, see [`LLM.md`](./LLM.md). The full machine-readable corpus is
+[`../../llms-full.txt`](../../llms-full.txt).
+
 ## @nifrajs/agent-telemetry
 
 Child-span telemetry for AI tool calls made through Nifra tool and MCP endpoints.
@@ -6893,6 +7578,59 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/aws-lambda
+
+AWS Lambda adapter for nifra - API Gateway HTTP API (payload v2) and Lambda Function URLs, buffered or streaming, with post-decode body limits and single-site header merging. Dependency-free.
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+## Install
+
+```sh
+bun add @nifrajs/aws-lambda
+```
+
+## Use
+
+```ts
+// handler.ts - one app per container, built at module scope
+import { handle, streamHandle, type LambdaEnv } from "@nifrajs/aws-lambda"
+import { server } from "@nifrajs/core"
+
+const app = server<LambdaEnv>()
+  .get("/", (c) => c.json({ ip: c.clientIp, requestId: c.env.context?.awsRequestId }))
+
+export const handler = handle(app) // API Gateway HTTP API (v2) + Function URLs
+// or, on a Function URL with InvokeMode: RESPONSE_STREAM:
+// export const handler = streamHandle(app)
+```
+
+How it holds the line:
+
+- **Post-decode body limits.** The body is decoded (base64 or UTF-8) and its real `byteLength` checked against `maxBodyBytes` (default 1,000,000 - match your app's setting if you changed it) *before* a `Request` is constructed. The event's own length claims are never trusted; over the limit answers a flat `413`.
+- **One header merge site.** Request headers come from the v2 `headers` map plus the separate `cookies` array in exactly one function; the array is canonical, so a `cookie` key smuggled into `headers` never reaches the app. Response `Set-Cookie` values travel in the result's `cookies` array, one entry each - never comma-joined.
+- **Base64 honesty.** Response `isBase64Encoded` is decided by a strict UTF-8 decode of the actual bytes, never by content-type guessing. Binary round-trips exactly; text ships as text.
+- **Client IP.** `event.requestContext.http.sourceIp` feeds core's client-IP seam; `X-Forwarded-For` trust stays where it belongs, in the app's `clientIp` server option.
+- **Flat errors.** Uncaught failures collapse to the same `{"ok":false,"error":"internal_error"}` 500 as every other nifra runtime - the event is never echoed.
+- **Freeze-safe `waitUntil`.** Background work settles before the handler returns, so Lambda's container freeze cannot strand it.
+
+The event and invocation context ride on `c.env.event` / `c.env.context` (type your app `server<LambdaEnv>()`). REST APIs (payload v1) and ALB events are out of scope; API Gateway does not support response streaming - `streamHandle` is for Function URLs.
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.
+
 ## @nifrajs/better-auth
 
 Mount [better-auth](https://better-auth.com) into a [nifra](https://github.com/nifra) app: one
@@ -7202,6 +7940,12 @@ Claude Code:
 claude mcp add nifra -- nifra mcp
 ```
 
+## Structured verification
+
+`nifra check --json` returns stable diagnostic codes and machine-actionable evidence. `nifra assure --json --strict` returns one versioned bundle with explicit pass, fail, and skip gate results plus a `green` or `red` verdict. Use `nifra fix --code NF-...` for a registered fix recipe, and `nifra contracts snapshot` to opt into route contract drift detection.
+
+Assurance configs may append application-supplied rule packs. Pack codes must not use the reserved `NF-` prefix. Rules are pure source scans and run after the built-in rules.
+
 Run the client from (or point it at) your project root. The protocol is hand-rolled
 (newline-delimited JSON-RPC 2.0) - no SDK dependency.
 
@@ -7645,6 +8389,27 @@ Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one
 bun add @nifrajs/i18n
 ```
 
+## Locale detection
+
+`negotiateLocale()` / `resolveLocale()` are pure: query parameter → cookie → `Accept-Language` →
+default, always answering from your `locales` allow-list (request input is matched, never echoed).
+The server plugin lives at `@nifrajs/i18n/detector` and needs `@nifrajs/core`:
+
+```ts
+import { localeDetector } from "@nifrajs/i18n/detector"
+
+app.use(
+  localeDetector({
+    locales: ["en", "fr", "de"],
+    defaultLocale: "en",
+    queryParam: "lang",
+    cookie: "locale",
+    persist: true, // pin an explicit ?lang= choice into the cookie
+  }),
+)
+// handlers see c.locale / c.localeSource; responses carry Content-Language
+```
+
 ## Docs
 
 - Reference: <https://nifra.dev/docs>
@@ -8124,6 +8889,17 @@ await serve(app, {
 })
 ```
 
+By default, `request.url` reflects the inbound `Host` header. Do not use that value for
+security decisions unless the deployment validates it. Set `allowedHosts` to reject unknown
+host authorities, or set `canonicalHost` behind a trusted proxy to build URLs from a fixed
+authority. If neither option is set, treat the host in `request.url` as client-controlled.
+
+## Static files
+
+The optional `static` root is served before `app.fetch` for GET and HEAD requests. It is a
+public asset directory and must contain nothing private: no secrets, source maps, build
+metadata, or user uploads.
+
 ## Graceful shutdown on signals
 
 Opt in to SIGTERM/SIGINT handling so a `docker stop` / Ctrl-C drains in-flight requests
@@ -8278,6 +9054,45 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/proxy
+
+Reverse proxy for nifra - stream requests to one fixed upstream origin with hop-by-hop hygiene, SSRF-proof by construction. Dependency-free.
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+## Install
+
+```sh
+bun add @nifrajs/proxy
+```
+
+## Use
+
+```ts
+import { server } from "@nifrajs/core"
+import { createProxy } from "@nifrajs/proxy"
+
+const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
+const app = server().mountFetch("/api", upstream, { stripPrefix: true })
+```
+
+The upstream is a **bare origin** fixed at construction - the forwarded URL is built by mutating a clone of that origin, never by resolving request-derived strings, so no request input can change which host is dialed. Hop-by-hop and `Connection`-nominated headers are stripped in both directions, forwarding metadata (`X-Forwarded-*`) is dropped unless `forwardClientIp: true`, upstream redirects are never followed, and TLS verification has no off switch. Unreachable upstreams answer a flat `502`; the deadline (`timeoutMs`, default 30s) answers `504`.
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.
+
 ## @nifrajs/runner
 
 Run requests through a nifra app and capture **structured results** - the shared engine behind the
@@ -8391,6 +9206,69 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/skills
+
+Portable agent skills for [Nifra](../../README.md) - one `SKILL.md` bundle, published to every agent
+surface that reads a `skills/` directory.
+
+A skill is loaded on demand: the agent sees only each skill's name and description until it decides
+one applies, then reads the body. That keeps Nifra's conventions out of the context window until they
+matter.
+
+```
+skills/
+  nifra/SKILL.md         entry point - MCP-first rule, the core loop, the non-negotiables
+  nifra-api/SKILL.md     typed routes, schemas, middleware, WebSockets, the never-throwing client
+  nifra-web/SKILL.md     file routing, loaders/actions, SSR, islands, the client/server boundary
+  nifra-verify/SKILL.md  check, assure, capabilities, manifest diff, the verification ladder
+```
+
+## Install
+
+**Pi**
+
+```sh
+pi install npm:@nifrajs/skills
+```
+
+**Claude Code**
+
+```sh
+/plugin marketplace add nifrajs/nifra
+/plugin install nifra@nifra
+```
+
+**Anything that reads a skills directory** (Cursor, `.agents/skills`, a project `.pi/skills`)
+
+```sh
+bun add -d @nifrajs/skills
+cp -R node_modules/@nifrajs/skills/skills/* .agents/skills/
+```
+
+## These skills are deliberately thin
+
+They teach shape and rules, not signatures. Signatures come from the MCP server, which is typechecked
+against the version installed in the project being edited:
+
+```sh
+bunx @nifrajs/cli init-agents      # register the MCP server in an existing app
+```
+
+Not in a Nifra project? The docs tools are hosted at `https://mcp.nifra.dev`.
+
+That split is the anti-drift design: a skill that restated the API would rot on the next release,
+while a skill that says "ask `nifra_types`" stays correct. Keep it that way when editing these files -
+if you find yourself pasting a signature in, reach for a tool reference instead.
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card, one cheap read instead of the whole
+corpus. For the wider framework: the repo's [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick
+reference, and [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run
+`nifra check` as the done-gate, or `nifra mcp` to give the agent live project tools.
+
+MIT licensed.
+
 ## @nifrajs/storage
 
 Blob storage for nifra - one `StorageAdapter` interface, several adapters. The **persistence half of
@@ -8651,6 +9529,7 @@ that every call carries and captures cookies via a shared jar.
 - `testSession<App>(app, { origin?, cookies? })` → `{ client: Treaty<App>, cookies: CookieJar }`.
 - `cookieJar()` → `CookieJar` - `header()` · `applyTo(headers)` · `store(response)` · `set` · `get` · `clear` · `size`.
   Honours removal (`Max-Age=0` / past `Expires`); other cookie attributes are ignored (in-process, same-origin).
+- `proveIdempotency({ run, runs? })` → a token-only proof that canonical effect ledgers replay identically.
 
 For a **stateless** request (no cookies), use `testClient` from `@nifrajs/client` directly.
 
@@ -9024,6 +9903,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 # Complete export index (generated from each package's src/index.ts)
 
+## @nifrajs/agent
+
+`AgentApprovalPort`, `AgentApprovalResult`, `AgentDefinition`, `AgentModelPort`, `AgentModelRequest`, `AgentModelResponse`, `AgentPendingContinuation`, `AgentPendingKind`, `AgentPorts`, `AgentRunResult`, `AgentStateStore`, `AgentStatus`, `AgentStepEvidence`, `AgentTelemetryPort`, `AgentToolContract`, `AgentToolDescriptor`, `AgentToolResult`, `AgentTranscript`, `AgentTurnBaseResult`, `AgentTurnError`, `AgentTurnInput`, `AgentTurnResult`, `AgentTurnState`, `createAgentState`, `createLocalProcessAdapter`, `ExecutionPolicy`, `ExecutionPolicyAdapter`, `LOCAL_PROCESS_LIMITATION`, `LocalProcessAdapter`, `LocalProcessAdapterOptions`, `LocalProcessPolicyError`, `LocalProcessRequest`, `LocalProcessResult`, `MemoryAgentStateStore`, `replayAgent`, `resumeAgent`, `runAgent`, `RunAgentOptions`, `turn`
+
 ## @nifrajs/agent-telemetry
 
 `agentTelemetry`, `AgentTelemetryOptions`, `consoleAgentExporter`
@@ -9032,6 +9915,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `AuthorizationRequest`, `Authorizer`, `createSessions`, `csrf`, `CsrfOptions`, `GuardOptions`, `isAuthorized`, `KVNamespaceLike`, `KVSessionStore`, `MemorySessionStore`, `MemorySessionStoreOptions`, `requireAuthorization`, `requireSession`, `requireUser`, `Session`, `SessionContext`, `SessionCookieOptions`, `SessionManager`, `SessionOptions`, `SessionRecord`, `SessionStore`
 
+## @nifrajs/aws-lambda
+
+`FetchHandler`, `handle`, `handler`, `LambdaContext`, `LambdaEnv`, `LambdaEvent`, `LambdaOptions`, `LambdaPlatform`, `LambdaResult`, `ResponseStream`, `streamHandle`
+
 ## @nifrajs/better-auth
 
 `authed`, `AuthedOptions`, `betterAuth`, `BetterAuthLike`, `BetterAuthOptions`, `getSession`, `Principal`, `PrincipalFor`, `requirePrincipal`, `requireSession`, `RequireSessionOptions`, `SessionOf`, `SessionUserOf`, `WithPrincipal`
@@ -9074,7 +9961,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/i18n
 
-`createFormatter`, `Formatter`, `Locale`, `Messages`, `negotiateLocale`, `NegotiateOptions`
+`createFormatter`, `Formatter`, `Locale`, `LocaleParts`, `LocaleSource`, `Messages`, `negotiateLocale`, `NegotiateOptions`, `ResolvedLocale`, `resolveLocale`
 
 ## @nifrajs/image
 
@@ -9116,6 +10003,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `prompt`, `Prompt`, `PromptInputError`, `PromptMessage`, `PromptOutputError`, `PromptRequest`, `PromptResponseFormat`, `RunOptions`
 
+## @nifrajs/proxy
+
+`createProxy`, `ProxyContext`, `ProxyHandler`, `ProxyOptions`
+
 ## @nifrajs/runner
 
 `AppLike`, `RequestSpec`, `runApp`, `RunOptions`, `runRequest`, `RunResult`
@@ -9130,7 +10021,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/testing
 
-`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AppLike`, `assertAdapterCertification`, `assertAdversarialContract`, `assertIncidentReplays`, `cacheStoreCertificationProfile`, `CapturedRequest`, `CapturedRequestInput`, `captureIncident`, `CaptureIncidentOptions`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `certifyAdapter`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `cookieJar`, `CookieJar`, `createFailureLab`, `defineCertificationProfile`, `eventDeliveryCertificationProfile`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `generateRegressionTest`, `GenerateRegressionTestOptions`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `jobStoreCertificationProfile`, `redactForEmission`, `replayIncident`, `ReplayIncidentOptions`, `runAdversarialContract`, `runFailureScenario`, `runtimeAdapterCertificationProfile`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `TestSession`, `TestSessionOptions`, `verifyAdapterCertification`
+`AdapterCertificationError`, `AdapterCertificationProfile`, `AdapterCertificationReport`, `AdversarialContractError`, `AdversarialContractOptions`, `AdversarialContractReport`, `AdversarialContractResult`, `AppLike`, `assertAdapterCertification`, `assertAdversarialContract`, `assertIncidentReplays`, `assertTrajectoryInvariants`, `cacheStoreCertificationProfile`, `CapturedRequest`, `CapturedRequestInput`, `captureIncident`, `CaptureIncidentOptions`, `CertifiableCacheEntry`, `CertifiableCacheStore`, `CertifiableDomainEvent`, `CertifiableEventDeliveryAdapter`, `CertifiableEventRecord`, `CertifiableJobStore`, `CertifiableRuntimeAdapter`, `CertifiableRuntimeServer`, `CertifiableStorageAdapter`, `CertificationCapabilityEvidence`, `CertificationCheck`, `CertificationCheckEvidence`, `certifyAdapter`, `checkTrajectoryInvariants`, `ContractCaseContext`, `ContractCaseKind`, `ContractCoverageGap`, `ContractCoverageGapCode`, `ContractReplay`, `ContractRuntime`, `ContractTarget`, `ContractTestApp`, `ContractWitness`, `cookieJar`, `CookieJar`, `createFailureLab`, `createTrajectoryTranscript`, `CreateTrajectoryTranscriptOptions`, `defineCertificationProfile`, `defineFaultProfile`, `EffectLedger`, `eventDeliveryCertificationProfile`, `FailureDirective`, `FailureEvidence`, `FailureInjectedError`, `FailureKind`, `FailureLab`, `FailureLabOptions`, `FailureReplay`, `FailureScenario`, `FailureScenarioReport`, `FaultProfile`, `FaultProfileFault`, `FaultProfileFaultKind`, `FaultProfileReport`, `FaultProfileScenario`, `FaultProfileScenarioReport`, `generateRegressionTest`, `GenerateRegressionTestOptions`, `httpToolAdapter`, `IdempotencyDivergence`, `IdempotencyProof`, `IncidentCapsule`, `IncidentReplayError`, `IncidentReplayResult`, `inProcessToolAdapter`, `jobStoreCertificationProfile`, `mcpToolAdapter`, `proveIdempotency`, `recordTrajectory`, `redactForEmission`, `referenceFaultProfile`, `replayIncident`, `ReplayIncidentOptions`, `replayTrajectory`, `ReplayTrajectoryOptions`, `runAdversarialContract`, `runFailureScenario`, `runFaultProfile`, `RunFaultProfileOptions`, `runtimeAdapterCertificationProfile`, `runTrajectory`, `shapeOf`, `storageAdapterCertificationProfile`, `testSession`, `TestSession`, `TestSessionOptions`, `testToolAdapter`, `TrajectoryInvariantId`, `TrajectoryInvariantOptions`, `TrajectoryInvariantResult`, `trajectoryRegressionId`, `TrajectoryReplayResult`, `TrajectoryRun`, `TrajectoryTranscript`, `verifyAdapterCertification`
 
 ## @nifrajs/ts-plugin
 
@@ -9142,7 +10033,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `routeStyles`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `SsrModuleLoader`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaDescriptor`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `routeStyles`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `SsrModuleLoader`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
 
 ## @nifrajs/web-preact