Turning Protections On and Off

Every protection and feature GioJS turns on by default, the gio.toml key that turns it off or loosens it, what that costs, and the few behaviors that stay fixed.

A new GioJS app is locked down without any configuration: cross-site requests are refused, responses carry security headers, connections and bodies are bounded, and the dev tools answer only your own machine. Each of these is a key in gio.toml, so an app with a reason to differ can turn one off - and the server tells you when you have. This page is the map: one table per area, with the key, its default, the value that turns it off, what you give up, and whether startup warns. Each section links to the full reference for its keys.

The rules every switch follows

• On by default. A feature section has enabled = true unless you write otherwise; sub-features have their own booleans, also true.
• 0 lifts a limit. Every numeric limit uses 0 for unlimited and every timeout uses 0 for none, in every section. To turn a feature off, use its enabled key, not a limit of 0. The exceptions: [cache] memory_max_entries must be at least 1 ([cache] enabled = false is the page cache's off switch); in [[rate_limits]], per_ip = 0 means no refill (only burst requests, ever: the strictest setting) and window_seconds = 0 is treated as 1 second; and [images] quality = 0 is treated as 1.
• Never silent. Turning a protection off, or lifting a limit that guards memory or connections to 0, logs one warn line at startup that names the key and what it costs - the Warns column below says which keys do. Timeouts and the prefetch budget lift without a warning, except [server] render_timeout_secs and [images] remote_timeout_secs, which warn: at 0, a render that never answers holds its connection and a worker slot indefinitely, and a slow remote source holds its request open. giojs-server --check-config and gio doctor report the same text under warnings, so CI can catch it before a deploy.
• Misspellings stop the server. An unknown key anywhere in gio.toml is a startup error naming the file, the line and the closest valid key. A typo such as enabeld = false can never leave a protection on that you meant to turn off, or the reverse.

# Print what startup would decide, without binding a port: errors (unknown keys,
# invalid values, rules that cannot be enforced) and one warning per loosened protection.
npx giojs-server --check-config

The command loads the .env files and gio.toml exactly as startup does, prints a JSON report and exits with 1 when the server would refuse to start. It never prints secrets.

Request protections

Enforced in the Rust server before any of your Node code runs. Reference: [security], [security.csrf], [security.websocket].

# Loosen instead of turning off, wherever you can.
[security.csrf]
trusted_origins = ["https://admin.example.com"]    # another origin of yours
exempt = ["/api/webhooks/*rest", "/saml/acs"]      # endpoints other sites post to

[[headers]]
path = "/embed/*rest"
[headers.headers]
x-frame-options = ""                               # let partners frame one section

Connection and request limits

These bound what one client, or a flood of them, can make the server hold. Reference: [server] and [[rate_limits]].

[[rate_limits]] rules themselves are opt-in: no rule, no limit. See Rate limits.

Client identity

Who the client is decides rate limits, the metrics allowlist, logs and ctx.ip. Reference: [server].

Operations endpoints

Reference: [metrics], [health], [revalidate]. See Endpoints & Headers for every /_gio path.

Development server

These keys apply only when the server runs with NODE_ENV=development (gio dev). In production /_gio/devtools* always answers 404. Reference: [dev].

Features

Turning one of these off saves work or hands it to something else (a CDN, an image service). None of them warns, except skew_protection = false and the image limits at 0.

What stays fixed, and why

A few behaviors have no switch. Each one either protects every other rule on this page or keeps one visitor's data away from another, and none blocks something an app legitimately needs:

• Canonical request paths. Repeated and trailing slashes collapse and escaped unreserved characters are decoded before any rule matches; dot segments, a raw \ and invalid % escapes get 400. Every guard, rate limit, header rule and CSRF exemption relies on one spelling of a path - with it off, /api//login or /api/%6Cogin would slip past a rule for /api/login. Browsers never send the refused forms.
• The closed /_gio namespace. Paths under /_gio/ that are not built-in endpoints answer 404 from Rust and never reach the app, so a dynamic route like app/[org]/settings cannot be rendered as /_gio/settings past its guard. Use any other prefix for your own routes.
• No error details in production. A failed render answers a generic page with a digest, and the message and stack are logged under that digest. Raw messages leak file paths, SQL and sometimes secrets; the digest leads you to the full log line. See Error Handling.
• Personalized renders are never shared. A render that read cookies, credentials, the client's IP or host is never stored, whatever revalidate says. A switch would hand one visitor's page to everyone. To cache and personalize, cache the shell with shell = 'cache' and personalize inside Suspense holes.
• The server-only import guard is opt-in per module: importing @gio.js/core/server-only or naming a file *.server.ts marks it. Removing the marker is the off switch; a global one would ship the marked modules (database clients, keys) to browsers. See server-only.
• Unknown gio.toml keys are errors. Tables for other tools go in [x-...] tables, which the server skips.
• Only GIO_PUBLIC_* variables reach the browser. The prefix is the opt-in; rename a variable to expose it. See Environment Variables.

Parts of switchable features stay fixed too:

• Open-in-editor requires a same-origin request (or Sec-Fetch-Site: none), and allowed_hosts = ["*"] does not cover it: it answers only localhost hosts from this machine, a specific [server] host and hosts listed by name, so no website, not even one rebound onto the dev server through DNS, can launch your editor.
• The image optimizer always rejects path traversal, never follows redirects for remote sources, and holds a local src to the guards of its URL.
• An adopted X-Request-Id must be 1 to 128 characters of letters, digits, ., _, : and -; anything else is replaced, which keeps log and header injection out.
• The revalidation token must be at least 32 bytes: a short bearer token can be guessed, and a long one costs nothing.

Example: an internal app behind a gateway

An admin tool reachable only through a company gateway that terminates TLS, adds its own headers and posts webhooks from a partner origin. Each loosening is deliberate, and startup lists them:

[server]
trusted_proxies = ["10.0.0.0/8"]          # the gateway; never 0.0.0.0/0
max_body_bytes = 20971520                 # 20 MiB uploads

[security]
default_headers = false                   # the gateway sets them (warns)
hsts = true                               # TLS ends at the gateway

[security.csrf]
trusted_origins = ["https://partner.example.com"]

[metrics]
ip_allowlist = ["10.0.0.0/8"]             # the Prometheus network; loopback only without it

[health]
details = false                           # no deployment id or topology on a public probe

--check-config accepts it and lists the one protection it turns off (output trimmed):

$ npx giojs-server --check-config
{...,"errors":[],...,"ok":true,...,"trustedProxies":1,"warnings":["[security] default_headers = false: responses no longer carry x-content-type-options, x-frame-options or referrer-policy (MIME sniffing, clickjacking and full-URL referrers are back) unless [security.headers] sets them"]}

Related

• Security - how each protection works
• Content Security Policy - the one protection that is opt-in
• gio.toml reference - every key, with the full reference block
• Production Checklist
• Upgrading to beta.8 - defaults that changed

Version history