Node runtime and production security

Place under ssr in the one root tavo.config.ts. Tavo.js supplies route modules and top-level plugins to generated builds; applications configure the remaining handler behavior. Document fields follow , and image fields follow .

• RenderDocumentOptions has title and unsafeHeadHtml. It has no raw document.head string alias.

• Prefer route head exports and escaped TSX metadata. unsafeHeadHtml is unescaped and must never contain user-controlled content.

• canonicalOrigin must contain only an HTTP(S) origin: no credentials, path, query, or hash.

• maxRequestBodyBytes defaults to 10 MiB for the Node handler.

• Cookie or Authorization requests bypass static response caching.

tsimport { defineConfig } from "@tavojs/core/config";

const reviewedBootstrapHtml =
  '<meta name="application-name" content="Acme">';

export default defineConfig({
  ssr: {
    canonicalOrigin: "https://app.example.com",
    trustedHosts: ["app.example.com"],
    maxRequestBodyBytes: 10 * 1024 * 1024,
    stream: true,
    document: {
      lang: "en",
      title: "Acme",
      unsafeHeadHtml: reviewedBootstrapHtml
    },
    images: {
      allowRemote: true,
      remotePatterns: [{
        protocol: "https:",
        hostname: "images.example.com",
        pathname: "/media/**"
      }]
    }
  }
});

applies this contract to the generated Node server. Low-level document and page render functions remain available when a platform needs a custom server integration.

• HTML, actions, plugin responses, images, and generated static assets receive baseline nosniff, referrer, permissions, and framing headers where applicable.

• Tavo.js does not invent a universal Content Security Policy. Add a deployment-specific policy and pass one request nonce through intentional inline content.

• The handler exposes invalidateCache(tags) and clearCache() for rendered and resolved cache invalidation.

tsimport { createServer } from "node:http";
import { createNodeRequestHandler } from "@tavojs/core/server";
import * as modules from "virtual:tavo-pages";

const handleRequest = createNodeRequestHandler({
  modules,
  trustedHosts: ["example.com"],
  stream: true,
});

createServer(handleRequest).listen(3000);

Origin validation applies to unsafe methods when validateOrigin is not false. A present Origin must equal the normalized request URL origin. Missing Origin is accepted by the Fetch handler; the Node handler still requires a local or configured trusted inbound host.

Configure remote loading through . The optional resolveHostname hook is a platform adapter with the exact signature shown below.

• The optimizer rejects private hostnames and private DNS results, and checks redirected locations again.

• Local absolute paths must remain inside publicDir.

• Set the Image component's unoptimized prop when the source should bypass the optimizer.

• Install the optional sharp peer only on servers that perform transformations.

• Deploy .tavo/build/client for fully client/static applications or run .tavo/build/server/start.mjs for request-time behavior.

• Plain tavo preview delegates to Vite preview. tavo preview --ssr checks for missing or stale output and runs tavo build first when required.

• Protect the external TLS, proxy header, CSP, secret injection, health-check, and process supervision boundaries on the hosting platform.

bashnpx tavo build
HOST=0.0.0.0 PORT=4174 node .tavo/build/server/start.mjs

• Exercise one SSR GET, one client navigation, one action, one plugin endpoint, one error response, and one remote image policy decision.

• Verify the public Origin observed behind the real reverse proxy.

• Confirm an untrusted Host and mismatched Origin receive 403 before mutation code runs.

• Confirm the monitor endpoint is hidden without the Bearer token.

bashnpx tavo check
npx tavo build --report-json
npx tavo preview --ssr
npx tavo monitor --url http://127.0.0.1:4174 --token "$TAVO_MONITOR_TOKEN" --once