This document describes Brace's security features and best practices for building secure applications.
- Authorization
- SQL Injection
- Sessions
- CSRF Protection
- Cross-Site Scripting (XSS)
- Content Security Policy
- Serialization
- Open Redirects
- Server-Side Request Forgery (SSRF)
- Trusted Proxies
- Cookie Security
- Static Files
- Response Compression
- WebSockets
- File Uploads
- Rate Limiting
- Deploying in a Container
- Installing and Updating Brace
- Ops Endpoints
- Analytics
- Outbound Mail
- Secrets Management
Every route — HTTP and WebSocket — carries a list of access requirements, and start()
refuses to run while any route has none and isn't explicitly marked .publicRoute(). A route
therefore cannot become public by being registered outside a guarded path, or by its author
forgetting a guard: the app fails to start (and its tests fail) instead.
app.defaultAccess(Access.session("userId", "/login")); // applies to every route
app.get("/", home::index).publicRoute(); // explicit, greppable opt-out
app.group("/admin", Access.check((req, s) ->
"admin".equals(s.get("role")) ? null : Result.forbidden()), admin -> { ... });Requirements are bound to the Route object at start(), not matched against the request
path, so a guard and a route can't disagree about a path: /admin/x/, /admin/%78 and
HEAD /admin/x reach the same route and run the same requirements. They run after plain
before(...) middleware (so a rate limiter sheds load first) and before the framework reads
the request body for the handler and for CSRF. The framework itself never buffers a body for a
request an access requirement rejects. The body is read earlier only if a plain before(...)
asks for it: req.body(), req.formParam(...), req.form(...) and req.file(...) read it
on first use, and a plain before runs ahead of access. The login limiter shown under Rate
Limiting does exactly that (req.formParam("username")), so on that path an unauthenticated
client's body is read, up to the upload limit, before any access requirement runs; that is the
limiter's job there, since the login route is public. Keep body-reading before(...) middleware
to the paths that need it. Rejections go through the normal response path, so security headers
and session write-back apply.
A request whose raw path has a segment that is exactly . or .. (/items/../y, /one/.)
is answered 404 without being matched against any route or static mapping, and without any
before(...) middleware, access requirement or handler running: no handler receives .. as a
path parameter, and a proxy that resolves dot segments for its own rules can't be made to
disagree with Brace about which route is being called. After-middleware does run for that 404,
as for any other, so it carries the app's security headers. When the path, as written or with
its dot segments resolved, falls under a guarded static mapping (/docs/./report.txt,
/x/../docs/report.txt), the 404 is also sent Cache-Control: no-store, whatever an
after(...) set.
Plain before(...) middleware never counts as access. The previous model —
requireSession("/admin/*", …) path-pattern guards — is removed.
The framework's own /ops/* routes follow the same rule: each is registered with the ops
credential requirement (ops:read or ops:control), the handlers carry no auth code, and an
ops route registered without one fails start(). The app's default access never applies under
/ops.
/ops/routes and the startup banner list each route's resolved access.
A staticFiles mapping is not a route, but it is inside the same model. Every mapping says who
may fetch its files, and start() (so also Brace.test()) refuses to run while one says
neither:
app.staticFiles("/assets", "public").publicFiles(); // everyone
app.staticFiles("/uploads", "/var/app/uploads", StaticFiles.UNTRUSTED)
.access(Access.session("userId", "/login")); // logged-in usersdefaultAccess(...)does not apply to a mapping, and neither doesdefaultAccess(Access.none()). A mapping's access is exactly what its.access(...)lists (all must pass). Inheriting a login default would put the login in front of the login page's own stylesheet; defaulting to public would publish an upload directory by omission. So there is no default, and an undeclared mapping is a startup error.- The requirements are bound to the mapping, not to a path pattern. They run when no route
matched the request's method and path and the mapping's prefix covers the path, at the same
point as a route's: after plain
before(...), before session-awarebefore(...), with the oneSessionthe request uses. They run before the path is decoded or the disk is touched, for every method, so every spelling that reaches the mapping's files is guarded, and a rejected request gets the same response whether or not the file exists. - A mapping serves
GETandHEADonly. Any other method on a path under a mapping (POST,OPTIONS, an unknown method) gets405withAllow: GET, HEAD. The 405 comes after the mapping's access has run, so an anonymous request to a guarded mapping still gets the rejection, and after session-awarebefore(...)middleware, which may answer first. The bundled/__brace/*assets answer other methods with405too. - A route under a mapping's prefix owns its path. With
staticFiles("/docs", dir)andapp.get("/docs/payroll.pdf", ...), the route answersGET(andHEAD) with its own access, and the mapping never serves/docs/payroll.pdfunder any method. (Before this,POST /docs/payroll.pdfskipped the route and was served the file by the mapping.) A request for that path under a method the route does not handle is answered in this order: the mapping's access; session-awarebefore(...); then the access of every route that owns the path, so a caller the route would refuse gets that same rejection (a login redirect, a 403) and learns nothing more; and only then405with the routes' methods inAllow. - A WebSocket route owns its path too. With
app.ws("/docs/live", ...)under that mapping, a plain (non-upgrade) request for/docs/liveis never served a file namedlive: it gets the socket route's access check, then426 Upgrade RequiredforGET/HEADor405withAllow: GETfor another method. start()logs a warning naming each mapping that has routes (WebSocket routes included) under its prefix, because every other file in that directory is still served under the mapping's access alone; a mapping at/is not warned about. Outside a mapping, a path that only matches a route under another method is a404, as before.- A mapping's prefix must start with
/.staticFiles("assets", dir)throws at registration; it used to start and never serve (and""behaved as/). - Nothing under a guarded mapping can be stored by a shared cache. A served file (200, 206, 304)
is sent
Cache-Control: private, no-cache, and a?v=fingerprint earns noimmutablethere. Every other response under the mapping (the access rejection, a 404, 405 or 416, an early response frombefore(...), an error) is sentCache-Control: no-store. This is enforced after after-middleware:Cache-Control,Expires,Pragma,CDN-Cache-Control,Surrogate-Control,Cloudflare-CDN-Cache-ControlandVercel-CDN-Cache-Controlare removed in any letter case, whatever set them, and the oneCache-Controlabove is set. start()refuses two mappings whose directories overlap (the same directory, or one inside the other, compared as written and with symlinks resolved) unless their access is the same: a guarded directory that a public mapping also serves, or one that a less strictly guarded mapping also serves, would be reachable through the weaker prefix. Built-in requirements are compared by value (twoAccess.session("userId", "/login")calls match); a customAccess.check(...)orAccess.checkRequest(...)matches only itself, so pass the sameAccessobject to both mappings if they are meant to match.start()requires every mapping's directory to exist. A directory created later could be a symlink into another mapping's tree, or a case-variant sibling of one on a case-insensitive volume, which the overlap check would never have seen. As a second line, a mapping answers 404 for a file whose real path is inside the directory of a mapping with different access, which covers a directory replaced by a symlink after startup.- The same URL prefix cannot be registered twice (
staticFilesthrows;/filesand/files/are the same prefix): only one of the two could ever serve. - The bundled
/__brace/*assets and/__brace/healthare not mappings and stay public. /ops/routes(methodSTATIC) and the startup banner list each mapping with its access.
A path-pattern before("/uploads/*", ...) is still not access, for the reasons above. For a
per-file decision (the owner of this file, not any logged-in user), serve the file from a route
instead: look the record up with db.findOwnedOr404(...) and return
Result.fileUnder(dir, name) or Result.download(...), with .untrusted() for uploads. Keep
those files in a directory no mapping serves. If the route does sit under a mapping's prefix,
the route wins for its methods and the mapping never serves that path, as described above.
When an access requirement rejects a request, on a route or a mapping, the response is sent
Cache-Control: no-store with the same header stripping as above, and
Vary: Accept, HX-Request is added (merged with any existing Vary), because
Access.session answers a page request with a 302, a JSON client with a 401 and an htmx
request with a 401 plus HX-Redirect. Without this, an app-wide after(...) that marks
responses public let a shared cache store the anonymous login redirect for a guarded URL and
serve it to logged-in users.
How a successful response from a guarded route is cached stays the app's decision. In dev
mode Brace warns once per route when such a response carries Cache-Control: public or
s-maxage.
Route access answers "may this user call this endpoint". It does not answer "may this user
touch row 42": GET /posts/{id}/edit is reachable by every signed-in user, and
db.findOr404(Post.class, id) returns anyone's post, so changing the id in the URL reads or
edits someone else's (an IDOR). Put the owner in the lookup:
var post = db.findOwnedOr404(Post.class, req.longPathParam("id"), "ownerId", session.get("userId"));
var doc = db.findOr404(Doc.class, id, d -> d.ownerId.equals(userId) || d.sharedWith(teamId));
var mine = db.query(Post.class, "ownerId = ?", userId); // lists: filter in the queryBoth lookups answer 404, not 403, for a row that exists but isn't the caller's, so the response
doesn't confirm it exists and ids can't be probed. A null owner (nobody signed in) matches
nothing. The owner field is an entity attribute path validated like findBy's and must be
hard-coded. Use the plain findOr404(type, id) only for rows every visitor may see.
Brace has no row-level filter that applies itself: every query that returns user-owned rows must carry its owner condition.
Database binds values only where the query says ?. The where-fragment and raw-query methods
(query, queryOne, queryOneOr404, count, exists, paginate, queryPage, hql, sql,
sqlQuery, sqlQueryLong) run the string they're given, so request data concatenated into it is
HQL or SQL injection: a quoted payload widens a WHERE to every row, and an ORDER BY built from
?sort= takes a CASE subquery that leaks any column one bit per request, including tables no
entity maps.
- Bind values with
?.db.query(Post.class, "title = ?", q), never"title = '" + q + "'". - Sort with
Sort.Sort.from(req, "sort", Map.of("title", "title", "date", "createdAt"), "createdAt DESC")lets the request pick a key from the map (-keyfor descending); an unknown key gets the default. Pass theSorttoquery,queryPageorpaginate. - Hard-code field names.
findBy,queryIn,countBy,existsBy,deleteByandfindOwnedOr404validate their field argument as an identifier, but it must still never come from the request.
The Database a request handler receives checks each where-fragment and raw query string
against the request's path, query and form values before running it. When the string contains
one, the call throws IllegalArgumentException in dev mode (-Dbrace.mode=dev) and in
Brace.test() apps, so the bug fails a test, and logs one warning per call site in production
(where a false positive must not break a page). The message names the parameter, not its value.
To keep coincidences out, values shorter than 3 characters and plain numbers are ignored, and a
single word (title, -createdAt) counts only as a token after ORDER BY (including an aliased
p.title), where it picks a column, not inside a literal, where it can't break out. Anything
with quotes, spaces, parentheses or operators counts anywhere. Form values include every value
of a repeated field; a body that isn't valid form encoding is skipped. A Sort.of(...) order is
checked like a fragment; a Sort.from(...) order is not, since the request only picked a key.
Production warnings repeat at most once a minute per call site and parameter.
What it does not catch:
- A single word or a number concatenated outside
ORDER BY:"id = " + req.pathParam("id")withidas the value is a tautology that returns every row, and isn't flagged, because flagging bare words everywhere would trip on ordinary code. - A value the handler transformed (trimmed, split into terms, re-cased) before concatenating it.
- JSON bodies, headers and cookies, and queries run outside a request (jobs,
withSession).Sort.of(...)is checked against the string you passed as well as the normalized order, so?sort=title%20descis caught even though it renders astitle DESC.
Every path parameter and query value is recorded (the request line is bounded at 8 KB, so there
are never many). The form body is recorded up to 1,000 values or 1 MB of text; a request past
that is over cap and cannot be fully checked. When such a request reaches a where-fragment, a
raw query or a Sort.of(...), the call throws in dev mode and Brace.test() (so padding a form
cannot slip a payload past a test), and production runs the query and logs an "over cap" warning
at most once a minute per call site.
It can also fire on safe code: a hand-written allowlist (switch (sort) { case "title" -> "title"; ... } concatenated after ORDER BY) looks the same as the injection it replaces. Use
Sort.from. The check is a backstop for the rules above, not a substitute.
Brace session cookies are encrypted using AES-256-GCM.
- ✅ Confidentiality: Data cannot be read by the client
- ✅ Integrity: Data cannot be tampered with
- ✅ Authenticity: Only the server can create valid sessions
✅ Safe to store (encrypted):
- User ID
- Email addresses
- Permissions, roles, or scopes
- User preferences (theme, language, timezone)
- CSRF tokens
- Flash messages (transient UI notifications)
- Shopping cart contents (within size limits)
Cookies have a 4KB size limit. For large session data:
- Use server-side storage (database, Redis, etc.)
- Store a session ID in the cookie and look up the rest server-side
- Algorithm: AES-256-GCM (Galois/Counter Mode)
- Key Derivation: PBKDF2-HMAC-SHA256 (100,000 iterations)
- Authentication: GCM mode provides built-in authentication (no separate HMAC needed)
- Nonce: Random 12-byte nonce per cookie. This prevents keystream reuse (the GCM
security requirement of a unique nonce per key) — it does not prevent replay. A
captured cookie can be replayed until it expires; replay is bounded by
_exp(below).
Every session cookie carries a server-enforced absolute expiry, _exp (epoch seconds),
inside the encrypted payload. On each read Brace rejects a cookie whose _exp is in
the past, returning an empty session. This is what bounds the lifetime of a stolen
cookie: the cookie's Max-Age attribute is only a client-side hint (a client can ignore
it and keep replaying the cookie), whereas _exp is checked by the server and cannot be
altered without the secret.
- Horizon:
SessionOptions.maxAge()when set to a positive duration; otherwise a 14-day default (so even "session-lifetime" cookies, which set noMax-Age, still expire server-side). - Fixed expiry from last write — no sliding window. A session is only re-minted when a
handler modifies it (
session.isModified()), so the expiry is measured from the last write, not the last request. An active user whose session is never modified will be logged out when the horizon elapses even with continuous activity. This is intentional; there is no per-response sliding refresh. To extend an active session, write to it (e.g. bump alastSeenvalue) on the requests that should renew it. - Reserved key.
_expis server-managed:session.set("_exp", …)is silently ignored, and_expis stripped from the decrypted data so it never appears viaget/has. - Absolute lifetime (
_abs)._expmoves forward with every write, so on its own a session that is used (or replayed) continuously never expires._absis stamped once, when the session is first issued, and carried unchanged: 30 days by default, ormaxAgeif that is longer (SessionOptions.absoluteMaxAge(Duration)).session.regenerate()restarts it. - No
_exp, no session. Cookies minted by 0.1.6 or earlier carry no_exp; accepted through 0.1.10, rejected since 0.1.11.
session.regenerate()at login and logout drops the CSRF token minted before the privilege change (one seen on a shared computer, or planted by a tossed cookie, is useless afterwards) and restarts the absolute lifetime.- Server-side revocation. A sealed cookie is valid until it expires, wherever it is copied
to.
app.sessionValidator(session -> boolean)runs once per request that reads a non-empty session, and on WebSocket upgrades; returning false makes the request anonymous and clears the client's cookie. Compare a version stored in the session at login with the user's current one to implement "log out everywhere", password-change logout and immediate demotion. Cache the lookup. - Secret rotation.
SessionOptions.previousSecrets(...)opens cookies sealed with earlier secrets and re-seals them with the current one, so rotating logs nobody out. The ops token secret is derived from the session secret, so ops clients re-authenticate after a rotation, and so is the key for WebSocket broadcasts between instances on Postgres: during a rolling rotation, instances on the old and new secret don't receive each other's broadcasts until all match. A secret that is public or compromised (thebrace newplaceholder, or one that leaked) must never be listed as previous: a listed secret still mints cookies. Startup refuses the shipped placeholder as a previous secret, and a cookie opened with a previous secret is honoured only if it carries_absand that deadline is no further out than the configured absolute lifetime. An empty previous-secret cookie opens as a brand-new session, inheriting no deadline.app.sessions(options)copies the options, so changing them afterwards has no effect, andstart()re-runs the secret checks under the mode the app starts in. Drop a retired secret once cookies sealed with it have expired. - Cookie name. Wherever the browser allows it (
Secure,Path=/, noDomain— every default production deployment) the cookie is__Host-brace_session. Only the exact host can set a__Host-cookie, over HTTPS, so a compromised or hostile sibling subdomain can't plant a session or CSRF token of its choosing, and a request reads only the name it would be given, so a tossedbrace_sessionis ignored. Plain-HTTP localhost keepsbrace_session, and so does an app behind a proxy that rewritesHostto a loopback address: thereSecureis inferred per request from the browser'sOrigin/Referer, which come and go, and the name must not change with them. Pass the real host through (see "Pass the realHostthrough") to get the prefix.
// Store user info directly in the encrypted session
session.set("userId", user.id.toString());
session.set("email", user.email);
session.set("role", user.role);
// Retrieve on subsequent requests
var userId = session.getLong("userId");
var email = session.get("email");
var role = session.get("role");For very large session data, you can still use server-side storage:
// Store only an opaque session ID in the cookie
session.set("sessionId", UUID.randomUUID().toString());
// Store large data in the database
var userSession = new UserSession();
userSession.sessionId = session.get("sessionId");
userSession.userId = user.id;
// ... store large data here ...
db.insert(userSession);Brace automatically validates CSRF tokens on mutating requests (POST, PUT, DELETE, PATCH).
- CSRF tokens are automatically generated and stored in the session
- The token must be included in requests as:
- Form parameter:
_csrf - Header:
X-CSRF-Token
- Form parameter:
- Validation happens automatically before your handler runs
- The token written into pages is masked per render:
${csrfField}(agg.jte.Contenthidden input; declare it@param gg.jte.Content csrfField = null) and${csrfToken}(the bare token, for a<meta>tag read by fetch or htmx) both carrybase64url(mask || token XOR mask)with a fresh random mask, so the value differs on every page. Validation accepts the masked form and the raw token alike. This keeps a compressed page from leaking the token through its size (see Response Compression). Outside a template, useCsrf.maskedToken(session)rather thanCsrf.getToken(session).
Every POST/PUT/DELETE/PATCH to a CSRF-protected route is also checked against the browser's own account of where it came from, before the body is read:
Sec-Fetch-Site: cross-site→ 403.same-origin,same-site(a sibling subdomain) andnone(typed, bookmarked) pass.- Without
Sec-Fetch-Site, anOriginheader must name the host the client addressed (X-Forwarded-Hostfrom a trusted proxy, elseHost); another host, orOrigin: null, → 403. - A request with neither header (curl, a server-to-server client) passes: it carries no ambient cookie to abuse.
This runs whether or not the app uses Brace sessions, so an app that authenticates with its own
cookie is covered too; with sessions it backs up the token check (a leaked token alone is not
enough cross-site). Routes with .csrf(false) are exempt.
.csrf(false) is for bearer-token routes. On a mutating route that uses the cookie session —
its handler takes the Session, or a session access requirement or a session-aware
before(pattern, BeforeSession) covers it — start() fails.
A route that is safe to force anyway states why with .csrf(false, "reason"), which is logged
at startup.
${csrfMeta} renders <meta name="csrf-token" content="…"> with a masked token, and the bundled
/__brace/csrf-htmx.js copies it into X-CSRF-Token on every non-GET htmx request. The token is only attached to same-origin requests, so an hx-post to a cross-origin URL (for example, with htmx's selfRequestsOnly turned off) does not leak it. The origin is checked when htmx sends the request, so a htmx:configRequest listener of the page's own that rewrites the path afterwards is covered too. A cross-origin htmx request never carries X-CSRF-Token from this helper, for any verb: a value already in the request's headers when the helper runs (hx-headers on the element or inherited from <body>, htmx.ajax(..., {headers}), an earlier listener), under any letter case, is removed. The helper cannot tell a third party's token from the app's own, and injected markup alone (<base href>) can turn a relative hx-post into a cross-origin request. A same-origin non-GET request carries the meta tag's token under exactly one header name; a same-origin GET keeps a value the page set itself. To send a chosen X-CSRF-Token to another origin, assign it in an htmx:configRequest listener added on document after the helper script is included.
CSRF validation is skipped for:
- GET, HEAD, OPTIONS requests (safe methods)
- Routes explicitly opted out with
.csrf(false)
CSRF validation is not bypassed by Content-Type: application/json. All mutating
methods on CSRF-required routes are validated regardless of content type. If your API
uses bearer-token authentication (no cookies), call .csrf(false) on those routes to
opt out explicitly.
POST with credentials. If your JSON endpoint authenticates via session cookies, either
validate the CSRF token (e.g. via the X-CSRF-Token request header) or use bearer
tokens with .csrf(false).
- For HTML forms: Include the CSRF token field (automatically available in templates)
- For JSON APIs with cookies: Either:
- Send the CSRF token in the
X-CSRF-Tokenrequest header - Use bearer token authentication and call
.csrf(false)on those routes
- Send the CSRF token in the
- For public APIs: Use API keys or OAuth, not cookie-based sessions
Templates escape ${...} for the context it lands in (JTE), and Brace's template output adds the
contexts where escaping alone doesn't stop script:
- URL attributes.
href,src,action,formaction,xlink:href,poster,cite,background,data,hx-get,hx-post,hx-put,hx-patch,hx-delete(anddata-hx-forms), on any tag. HTML escaping leavesjavascript:alert(1)intact, and browsers strip tabs, newlines and leading control characters before reading the scheme, sojava\tscript:is a script URL too. Alsoto/from/by/valueson SVG<set>and<animate>, which can set anhref. The whole value, template text and every${...}, is held until its closing quote and normalized the same way, with character references decoded (href=" ${url}"starts with a space, not with a fragment). If the template's own text fixed the scheme or made the URL relative (href="mailto:${email}",href="/users/${id}"), it's kept; if user data decides the scheme (href="${url}",href="${a}${b}",href="${scheme}://${host}") onlyhttp,https,mailtoandtelpass, plus rasterdata:image/URLs (png, jpeg, gif, webp, avif, bmp; never SVG) onsrcandposter. Anything else renders asabout:invalid#blocked. One scheme the template can't choose for data: ajavascript:orvbscript:URL with any${...}in it (href="javascript:go('${id}')") is blocked as well, because the browser undoes both HTML escaping and percent-encoding before it runs the code. Put the value in adata-*attribute and read it from a script file. - Script attributes.
on*,hx-on*(hx-on:click,hx-on-click,data-hx-on:*),hx-vals,hx-vars,hx-headers,hx-requestandhx-trigger. User data is escaped with\uXXXXsequences for every character that can end a string or start markup or a template substitution, which is valid in JavaScript strings, template literals and JSON, so JSONhx-vals/hx-headerskeep working with quotes in the data. This protects data written inside a quoted string in the attribute's code (onclick="go('${id}')",hx-trigger="click[check('${id}')]"). It does nothing for data that is the code itself:onclick="${handler}",onclick="go(${id})"orhx-trigger="${trigger}"run whatever the value says (click[alert(1)]is a valid trigger with a filter expression, and has no character that needs escaping). Never put user data there outside a quoted string. HTML escaping alone is undone by the browser before the code runs ('is a quote again), and JTE's JavaScript escaping foron*left&alone, so an entity in user data still closed the string. When data is the wholehx-vals/hx-headers/hx-requestvalue (hx-vals='${json}') it is attribute-escaped instead, so JSON the handler built stays intact. htmx evaluates such a value when it starts withjs:orjavascript:after trimming (JavaScript'strim(), which strips U+00A0, U+FEFF and the other Unicode spaces): if user data supplies any part of that prefix, in one${...}or several, the value renders as{}. Ajs:the template wrote itself is kept. (hx-varshas no such prefix: htmx evaluates all of it, always. It is deprecated in htmx; usehx-vals.) srcdoc. User data is escaped twice, so it is text inside the frame, not markup. Template markup insidesrcdocisn't URL-checked; an HTML preview should be sanitized HTML written with$unsafe{Html.escape(...)}in an iframe withsandbox.<script>bodies. In a<script>tag written in any letter case, in HTML or inside<svg>/<math>, every character of user data other than ASCII letters, digits,_,,and non-ASCII characters is written as a\uXXXXescape (O'Brienis writtenO\u0027Brien; a backslash is written\\). A JavaScript string in either quote style, a template literal and a JSON string read the escapes back as the original text, and a regex literal matches it literally, so the value the script sees is unchanged: only the page source looks different. What is left has nothing in it that is syntax to JavaScript or to an HTML parser (no quote,<,>,&, space,=,/,`or$), so data can't end its string, can't spell</script>,<!--or${, and can't read as markup whatever the browser makes of the script. As in a script attribute, that protects data inside a quoted string (var name = "${name}";, a template literal, a regex literal). Data outside a string is not supported:var n = ${count};runs whatever the value says while it is all letters and digits, and is a syntax error as soon as it has anything else in it (1.5,-3). Pass numbers and objects in a string (Number("${price}"),JSON.parse) or in adata-*attribute. Things to know:- Data blocks.
<script type="application/json">{"name": "${name}"}</script>gets the same escaping, which is valid JSON for any value:JSON.parsereturns the original text. A block that is neither JavaScript nor JSON (<script type="text/template">) gets it too, and there the escapes show as text: put client-side template markup in a<template>element, where${...}is escaped as HTML. - Scripts inside
<svg>or<math>. A browser reads these as markup, not as raw text:a<bor0<i ?in the code opens a tag, and what follows it is attribute names and values to the HTML parser while it is still JavaScript to the script. The escaping above holds in a string wherever the HTML parser takes it to be. Where Brace sees that a${...}lands inside such a tag and outside a quoted value (a string that doesn't follow=is in attribute-name position), it writes every character as an escape, letters and digits included (okis written\u006f\u006b); the script still reads the text back. A self-closing<script href="a.js"/>or<style/>is a complete element there. In HTML it is not:<script src="a.js"/>opens a script that runs to the next</script>, so always write<script src="a.js"></script>. - Scripts wrapped in
<!-- ... -->. After<!--and a<scriptin the text (as indocument.write("<script src=x></script>")), a browser does not end the element at the next</script>. Brace follows that, so data after it is still escaped as script. - Comments in a script or style. JTE removes comments when it compiles a template:
<!-- -->in markup,//to the end of the line and/* */in a<script>,/* */in a<style>. So a// <![CDATA[line in a script is not in the page. JTE 3.2.1 also has a bug here: when a template's first comment comes before its first${...}or@if, and the text between that comment and the next${...}has a<directly followed by a letter with no>after it (for (i = 0; i<n; i++) { f("${x}"); }), JTE drops all the template text before the comment, the<script>tag included. The script's source then shows as page text on every render, andi<n; ...is a real tag. Brace can't put the text back; it escapes the data in that tag whole (as above), so the result is a visibly broken page and not an injection. If a page loses its top, write the comparison with spaces (i < n), or move or remove the comment.
- Data blocks.
- CSS. In a
<style>body and in astyle=""attribute, every character of user data other than letters, digits, spaces,# % . _ -and non-ASCII characters is written as a CSS hex escape (;becomes\3b). An escaped character is never CSS syntax, so data can't close its declaration or rule and add a selector (the usual way to leak a hidden field's value under a policy that allows inline styles), and can't openurl(...). Plain values (red,#ff0000,50%,12px solid) are unchanged, and data inside a quoted CSS string (content: "${label}",url("${image}")) reads back as written. A value that needs CSS syntax of its own,rgb(1, 2, 3)or a whole declaration list instyle="${styles}", no longer works as data: build it from plain values in the template. Not covered: user data used as a selector or property name can still be any identifier.
Brace decides the context from the HTML it has written so far, not only from where the ${...}
sits in the template source, so the rules above also apply to data a @template call or a
content block writes inside an attribute value (JTE alone escapes that as body text). It follows
the HTML parser's rules for tags, comments, <script>/<style> bodies and SVG/MathML content.
Where its reading and JTE's differ, the data gets the rules of both: the URL check if either says
URL attribute, script escaping if either says script. That shows as over-escaped text (\u0027
for a quote), never as unescaped data. Two cases get the strictest treatment. Data that lands
inside a tag but outside a quoted value, whatever JTE reports, is written with every character
escaped (JTE refuses ${...} there at compile time, so a template reaches it only in a script
or style body that a browser reads as markup). And an hx-vals, hx-headers or hx-request
value that Brace's reading is not inside of can't be judged whole, so none of its data is
written: it renders as {}. Two things Brace reads differently from a browser, on
purpose: the text of <title> and <textarea> is read as markup, and SVG/MathML content that
isn't well formed (an end tag with no matching start tag inside the <svg>) is read as HTML from
there on. Also read as HTML: <annotation-xml> whatever its encoding, and a MathML text
element inside <svg> or an SVG one inside <math>.
Both the hot-reload and precompiled render paths use this output. $unsafe{...} bypasses it, as
does Result.html(...), which is a raw sink.
At input, @SafeUrl on a form field accepts only an absolute http/https URL; outside
templates, Url.isSafe(url) / Url.safe(url) apply the template rule (for a URL sent in JSON
for a client to use as a link).
htmx evaluates code. Bundled htmx runs with allowEval and allowScriptTags on unless a
page sets <meta name="htmx-config" content='{"allowEval":false,"allowScriptTags":false}'>.
With them off, hx-on*, js: values and trigger filters don't run, and neither do <script>
tags in swapped-in HTML, so a template mistake can't become code that way. Recommended unless a
page relies on them.
Escaping is the first defence against XSS; a Content-Security-Policy is the second. It decides
what an injected tag can do once one gets past escaping. Brace ships it as
SecurityHeaders.strict():
app.after(SecurityHeaders.strict());That sets the SecurityHeaders.defaults() headers (nosniff, X-Frame-Options: DENY,
Referrer-Policy, Permissions-Policy) plus:
Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'
script-src 'self': scripts load only from the app's origin. Inline<script>bodies,on*=attributes,javascript:URLs andeval(including htmx'shx-on:*, which compiles its handler withFunction) don't run. Brace's/__brace/htmx.min.jsand/__brace/csrf-htmx.jsare same-origin and load normally.default-src 'self'covers styles, images, fonts and fetches, so inline<style>blocks andstyle=""attributes are blocked as well. htmx inserts a<style>for its request indicators at startup; under this policy that only logs a console violation. Add<meta name="htmx-config" content='{"includeIndicatorStyles":false}'>to the layout to stop it.object-src 'none',base-uri 'none': no plugins, and an injected<base>can't re-point the page's relative script URLs.frame-ancestors 'none': the CSP form ofX-Frame-Options: DENY.form-action 'self': an injected<form>can't post the page's data to another site.
After-middleware runs on every response (handlers, static files, 404s, 500s, CSRF rejections),
so the policy covers them all. defaults() deliberately has no CSP: adding one would silently
break apps that still have inline scripts. Avoid 'unsafe-inline' in script-src in a custom
policy (SecurityHeaders.builder().contentSecurityPolicy(...)): it allows every inline script,
injected ones included, which leaves the policy doing nothing against XSS. brace check warns
when GET / has no CSP, or one whose scripts allow 'unsafe-inline' without a nonce or hash.
The /ops pages carry the framework's own policy, which replaces the app's on those responses
(see Ops pages in the browser).
Brace entities follow the convention of public fields for simplicity. When serializing objects to JSON with Json.of() or Result.json(), all public fields are included in the response — including sensitive columns like passwordHash, API keys, or PII.
// ❌ Dangerous: serializes all public fields, including passwordHash
@Entity
public class User {
public Long id;
public String email;
public String passwordHash;
}
var user = db.find(User.class, id);
return Result.json(user); // Leaks passwordHash to HTTP response✅ Safe: DTO exposes only intended fields
public record UserResponse(long id, String email) {}
var user = db.find(User.class, id);
return Result.json(new UserResponse(user.id, user.email)); // Only public fields from recordBrace logs a WARN message (once per entity class per process) when Json.of() detects an @Entity-annotated object being serialized, to help catch this pattern in development. Enable production log monitoring to detect any misuse — the message includes the entity class name and hints at the likely leaked field name.
A handler that redirects to a user-supplied destination is an open redirect — an attacker crafts a link on your domain that lands users on a phishing site, with your domain's credibility behind the link they clicked:
// ❌ Dangerous: ?next=https://evil.example sends the user to the attacker's site
return Redirect.to(req.queryParam("next"));Redirect.to() (and Result.redirect()) deliberately accept any location — absolute URLs, protocol-relative URLs (//evil.example), anything — because server-controlled redirects legitimately need all of those. The vulnerability is feeding them untrusted input.
// ✅ Safe: only local paths accepted; throws IllegalArgumentException otherwise
return Redirect.toLocal(req.queryParam("next"));Redirect.toLocal(path) — and Redirect.permanentLocal(path) for 301s — validate with an allowlist: the path must start with exactly one /. Rejected: null/empty, absolute URLs (https://evil.example), protocol-relative URLs (//evil.example), backslash bypasses (/\evil.example — browsers normalize \ to /), and literal ASCII control characters.
- Any redirect target derived from request data (query param, form field, header) goes through
toLocal/permanentLocal - Server-controlled destinations (string literals, paths built with
Url.to()) can useRedirect.to()/Result.redirect()freely - Catch the
IllegalArgumentExceptionif you want a fallback (e.g. redirect to/) instead of a 500 on a tamperednextparameter
Any feature that fetches a URL a user supplied (import from URL, link previews, webhook "send a test", avatar from URL) makes requests from your server, with your server's network position. Pointed inward, it reads things no outside client can reach:
// ❌ Before 0.1.11: ?url=http://169.254.169.254/hetzner/v1/userdata returned the server's
// cloud-init user-data, which often holds secrets. http://172.17.0.1:5432/ reached the Docker
// bridge, http://localhost:8080/ops/... the app itself.
var preview = Http.get(req.queryParam("url")).fetchString();Since 0.1.11, Http refuses destinations that aren't on the public internet, for every call:
fetch, fetchString, fetchBytes, fetchJson, stream, fetchEvents and multipart().
Before sending, it resolves the host and throws Http.BlockedDestinationException if any
address the name resolves to is:
- loopback (
127.0.0.0/8,::1), unspecified (0.0.0.0, which reaches the local host on Linux,::) or0.0.0.0/8 - private: RFC 1918 (
10/8,172.16/12,192.168/16), CGNAT (100.64/10), IPv6 ULA (fc00::/7) - link-local (
169.254/16, which is where cloud metadata services live,fe80::/10) and IPv6 site-local (fec0::/10) - multicast and broadcast (
224/4,ff00::/8,255.255.255.255), reserved (240/4), benchmarking (198.18/15,2001:2::/48), documentation and other special-purpose ranges (192.0.0/24,192.0.2/24,198.51.100/24,203.0.113/24,192.88.99/24,2001:db8::/32,3fff::/20), Teredo (2001::/32), and any IPv6 outside global unicast2000::/3 - an IPv6 form that carries one of the IPv4 addresses above: IPv4-mapped (
::ffff:127.0.0.1), IPv4-compatible (::127.0.0.1), NAT64 (64:ff9b::a9fe:a9fe) and 6to4 (2002:7f00:1::) - Azure's WireServer,
168.63.129.16, a platform endpoint in a public range
The check runs on the resolved address, not the URL text, so http://0.0.0.0/,
http://[::ffff:127.0.0.1]/ and a hostname whose DNS record points at 10.0.0.5 are all refused.
A numeric host must also be a plain dotted quad: 2130706433, 0177.0.0.1, 0x7f.1 and 127.1
are refused outright, because readers disagree about them (Java reads 0177.0.0.1 as decimal
177.0.0.1, an HTTP proxy using inet_aton as octal 127.0.0.1). Nothing is sent to a refused
destination. The exception's message names only the host; the resolved address is on
e.address() for your logs, so a message shown to a user doesn't map internal names to private
IPs.
Http.isPublicAddress(InetAddress) is the same classifier, for rejecting a URL when a user
enters it rather than when you fetch it.
A request you make on purpose to your own infrastructure (a sidecar, an internal API, a URL from your own config) opts out per call:
var health = Http.get(config.get("search.url") + "/health").trusted().fetch();.trusted() turns the check off for that request only. Never call it on a URL that came
from a user, a database row a user wrote, or a redirect Location from a server you don't
control; that is the request the default exists to stop. There is deliberately no global off
switch.
Http never follows redirects. To follow one, read header("Location") and make a new Http
call with it, which checks the new destination too. Don't hand the Location to another
client, and don't add .trusted() to the follow-up unless you trust wherever it points.
Buffered fetches (fetch, fetchString, fetchBytes, fetchJson, and the error body of
fetchEvents) stop at 10 MB by default and throw Http.ResponseTooLargeException: at once
if Content-Length says the body is larger, otherwise as soon as the bytes read pass the limit,
without downloading the rest. Raise or lower it per call with .maxResponseBytes(n). stream()
is not capped, because it hands you the body to read: bound what you read yourself.
The same calls are bounded in time. .timeout(...) (default 30s) is the deadline for the
whole exchange, response headers and body together, and .idleTimeout(...) (default 30s) bounds
each wait for more body bytes. Either closes the connection and throws
Http.StreamTimeoutException. Without them, a hostile server behind a user-supplied URL could
send headers at once and then stall, or drip one byte every 29 seconds under the size cap, and
hold the request thread (and its pooled database connection, in a DbHandler) indefinitely; a
few dozen such requests would exhaust the pool. That was the case for buffered fetches until the
2026-11 security review (M8): timeout used to cover only the wait for headers. The error body
fetchEvents reads on a non-2xx status gets the same 30s default, though the event stream
itself has no deadline unless you set one.
A buffered call cannot be configured out of its deadline: .timeout(null) removes the deadline
only for stream() and fetchEvents, and means the 30s default for every fetch* call. Zero
or a negative duration throws IllegalArgumentException, and a duration over 365 days (for
example Duration.ofSeconds(Long.MAX_VALUE)) is clamped to 365 days rather than overflowing.
An attacker who controls a domain's DNS can answer with a public address when it's checked and a
private one when it's connected to. The robust defense is to connect to the exact address that
was checked. java.net.http doesn't support that cleanly (the request URI would have to carry
the IP, which needs the restricted Host header, a JVM-wide setting read once at startup, plus
per-hostname TLS settings), so Http narrows the window instead:
- The JDK resolves the name for the connection through the same JVM address cache that the check just read, so it normally connects to an address that was checked. The JVM caches lookups for 30 seconds by default regardless of the DNS record's TTL.
- The name is checked again when the response headers arrive. If its cache entry expired in the instant between the check and the connect and the new answer is private, the JVM has cached that answer, so the second check refuses it and the response is discarded before your code reads any of it.
So under the default JVM settings a rebinding attack can at most make a blind request (the request is sent, the response never reaches the caller), and only if it lands a cache expiry in a window of a few milliseconds. For https not even that: only a TLS handshake reaches the internal address, and it fails, because the certificate is still verified against the original hostname, which an internal server can't present. To keep it that way:
- Don't set
networkaddress.cache.ttl=0(orsun.net.inetaddr.ttl=0), or anything short. With the cache off, the check, the connect and the re-check each do a fresh lookup, so a rebinding name can answer public to both checks and private to the connect: the request (method, headers, body, any bearer token) goes to the internal address and the response can be read. The same holds when the response takes longer than the remaining cache lifetime.Httplogs a warning once when the TTL is under 10 seconds. - Prefer https for user-supplied URLs. If the feature allows it, refuse
http://URLs before callingHttp. - Block metadata and internal ranges at the network layer too (firewall the container's
egress to
169.254.169.254and your private subnets), so.trusted()misuse or another HTTP client isn't the only line.
If the JVM is configured with an HTTP proxy (http.proxyHost/https.proxyHost), the proxy makes
the connection and does its own DNS lookup, so the check (which runs on the local lookup) and the
re-check describe what the app resolved, not where the proxy connects. Configure the proxy to
refuse internal destinations itself. The check also needs local DNS: behind an egress proxy that
is the only resolver, every call without .trusted() fails with UnknownHostException.
The check is in Http. Storage, WebhookNotifier and anything built directly on
java.net.http or another library don't apply it; they take URLs from your configuration, not
from users. If you must fetch a user's URL with something else, resolve it and check every
address with Http.isPublicAddress first, and accept that the DNS-rebinding window above is
then wider.
When running behind a reverse proxy (nginx, Caddy, load balancer), you must explicitly configure trusted proxies.
Without trusted proxy configuration, attackers can spoof their IP address by sending fake X-Forwarded-For headers, bypassing:
- Rate limiting
- IP-based access control
- Audit logs
- Geofencing
// Trust specific proxy IPs
app.trustedProxies("10.0.0.5", "10.0.0.6");
// Trust the reverse proxy's network (a Docker network, a VPC subnet for the load balancers)
app.trustedProxies("172.18.0.0/16");
// From config or the environment: comma-separated, blank or unset means none
app.trustedProxies(config.get("trusted.proxies")); // the scaffold sets TRUSTED_PROXIESTrust the proxy, not the private address space. Every address in the list can set
req.ip() to anything it likes. 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 trusts every
container on a Docker host (bridge networks, Swarm overlays and their default address pools all
come from those ranges) and every machine in a typical VPC, so any of them can forge
X-Forwarded-For and pose as any client: rate limits, IP allowlists and audit logs all believe
it. List the proxy's own address, or the subnet of a network that only the proxy shares with
the app.
Behind Traefik on Dokploy, the proxy network is dokploy-network:
docker network inspect dokploy-network -f '{{range .IPAM.Config}}{{.Subnet}} {{end}}'Trusting that subnet is far narrower than a whole private range, but Dokploy attaches every app
it routes to dokploy-network, so any other app on the same host can still forge the header.
That is acceptable when you run every app on the host. If you don't trust the other apps, trust
only Traefik's own address, and give the Traefik container a fixed address on that network so
it survives a restart.
Unconfigured proxy warning. Behind a proxy that isn't trusted, req.ip() is the proxy's
address for every client: RateLimiter.perIp becomes one shared bucket (one client can lock
everyone out of login), and analytics sees a single visitor. When a peer on a private or loopback
address sends X-Forwarded-For or Forwarded and isn't a trusted proxy, Brace logs a warning
naming the address, once per process.
Behind Cloudflare, use the built-in preset instead of pasting CIDRs. It ships with
Cloudflare's published egress ranges (cloudflare.com/ips); .autoRefresh() keeps them synced
by re-fetching the published lists on a background virtual thread (daily, hourly retry after a
failure — the bundled list serves until the first fetch succeeds, and a failed or partial fetch
is discarded wholesale so the trust set never shrinks on a network blip). .plus(...) trusts
additional hops of your own — those survive refreshes:
app.trustedProxies(TrustedProxies.cloudflare().autoRefresh());
// with nginx between Cloudflare and the app, also trust the local hop:
app.trustedProxies(TrustedProxies.cloudflare().plus("127.0.0.1", "::1").autoRefresh());Trusting Cloudflare's ranges is only sound when the origin is reachable exclusively through
Cloudflare (firewall the origin, or use Authenticated Origin Pulls at your TLS terminator).
A client that connects to the origin directly is an untrusted peer whose forwarding headers
are ignored — the safe failure mode — but hiding the origin is what keeps attackers from
bypassing Cloudflare entirely. Note that Cloudflare's egress IPs are shared across all
Cloudflare customers; the rightmost-untrusted algorithm below stays spoof-safe regardless,
because Cloudflare itself appends the true connecting address to X-Forwarded-For.
- Without configuration:
req.ip()uses socket remote address only (ignores headers) - With configuration:
req.ip()parses the forwarding header only if the immediate peer is trusted
One forwarding header, chosen explicitly. Brace reads the client address chain from exactly
one header: X-Forwarded-For by default, or RFC 7239 Forwarded (its for= parameters) when
you opt in. The other header is ignored. Reading both was a spoofing hole: a proxy that sets one
of them usually passes a client-sent copy of the other through untouched, so a client behind a
Forwarded-only proxy could send X-Forwarded-For: 6.6.6.6 and become 6.6.6.6.
app.trustedProxies("10.0.0.5"); // X-Forwarded-For
app.trustedProxies(new TrustedProxies("10.0.0.5").useForwardedHeader()); // ForwardedChoose the header your outermost trusted proxy writes. nginx ($proxy_add_x_forwarded_for),
Caddy, Traefik, Cloudflare and the common cloud load balancers write X-Forwarded-For. If
your proxy writes only Forwarded, opt in, and if it might pass a client's X-Forwarded-For
through, that header is now harmless.
If the header arrives on several lines (two proxies that each add a line, or a client line plus the proxy's), every line is read, in wire order, as one list.
When the forwarding header is consulted, Brace uses rightmost-untrusted semantics: it walks
the list from right to left, skips any entry whose address falls inside a trusted CIDR, and
returns the first untrusted address (an empty entry or a Forwarded element without for=
reached on the way ends the walk with unknown; see below). This is the correct algorithm because real proxies
append the connecting client's address — the leftmost entries were written by the client and
can be forged.
Examples:
X-Forwarded-For |
Trusted CIDRs | req.ip() |
|---|---|---|
1.2.3.4 |
10.0.0.0/8 |
1.2.3.4 |
spoofed, 9.9.9.9 |
10.0.0.0/8 |
9.9.9.9 (rightmost untrusted, not attacker-supplied leftmost) |
203.0.113.9, 10.0.0.2, 10.0.0.1 |
10.0.0.0/8 |
203.0.113.9 (both proxies trusted) |
10.0.0.1, 10.0.0.2 |
10.0.0.0/8 |
10.0.0.1 (all trusted → leftmost) |
Dual-stack. TrustedProxies matches addresses by binary value and never resolves names. An
IPv4 CIDR also matches the IPv4-mapped IPv6 form of its addresses (10.0.0.0/8 matches
::ffff:10.1.2.3), so no extra entry is needed for a proxy seen through a dual-stack socket. IPv4
and IPv6 loopback are different addresses, though: 127.0.0.1 does not match ::1. If your proxy
can connect over either, list both:
app.trustedProxies("127.0.0.1", "::1");An IPv6 peer is matched and reported without brackets and in canonical form: Jetty gives the
socket address as [0:0:0:0:0:0:0:1], and Brace normalises it where the address enters the
framework, so a trusted IPv6 proxy is recognised and a direct IPv6 client's req.ip() is ::1.
The form of req.ip(). Always canonical, whether it came from the socket or a header, so
comparing it with a string is reliable:
| Address | req.ip() |
|---|---|
| IPv4 | dotted decimal: 203.0.113.9 |
| IPv6 | RFC 5952: lower-case hex, no leading zeros, the longest run of zero groups as ::, no brackets, no port: 2001:db8::5, ::1 |
IPv4-mapped IPv6 (::ffff:6.6.6.6) |
the IPv4 address: 6.6.6.6 |
| With a zone id | the zone kept as written: fe80::1%eth0 |
| No usable address | the literal string unknown (see below) |
So 2001:DB8:0:0:0:0:0:5, [2001:db8::5]:443 and 2001:db8::5 in a header are all
2001:db8::5. Write the addresses you compare against in the same form, or match with
new TrustedProxies("2001:db8::/32").isTrusted(req.ip()), which compares binary values.
X-Forwarded-For(the default client-address header)Forwarded(RFC 7239), instead ofX-Forwarded-For, withuseForwardedHeader(): elements split on,, parameters on;, neither inside a quoted-string (for="[2001:db8::1]:4711"). Elements are split from the right, so the element your proxy appended is delimited by its own text: an unbalanced quote in what the client sent (for="x) spoils only the client's element and cannot swallow the proxy'sX-Forwarded-Proto— the original scheme, for the session cookie'sSecureattributeX-Forwarded-Host— the host the client addressed, for theSecuredecision, the session cookie's__Host-name, the cross-siteOriginchecks (CSRF, WebSocket, ops) and analytics. The entry used must be ahostorhost:port(a name, an IPv4 address or a bracketed IPv6 address); anything else is ignored andHostis used
All of them are ignored unless the immediate peer is a trusted proxy. Each is read from every
line it arrives on, in order, as one list. For X-Forwarded-Proto and X-Forwarded-Host Brace
takes the rightmost entry, the one the nearest proxy added: behind a proxy that appends to
these headers, or passes a client's copy through, the leftmost entry is whatever the client sent.
Your proxy must set (overwrite) both headers, as the nginx example below does with
proxy_set_header; a proxy that only passes them through lets a client choose them.
unknown. req.ip() is always a canonical IP address literal or the string unknown. It is
unknown when the request came from a trusted proxy and the proxy's header names no usable
client:
- the entry the walk selects is not an address (
unknown,_hidden, an obfuscated RFC 7239 identifier, a malformed element, or anything a client managed to put there); - the header is present but empty, or (for
Forwarded) has nofor=; - the entry the walk reaches first after the trusted proxies is empty, or (for
Forwarded) an element withoutfor=. The walk only steps past entries that are trusted-proxy addresses, soForwarded: for=6.6.6.6followed by the proxy's ownForwarded: proto=httpsline, orX-Forwarded-For: 6.6.6.6followed by an emptyX-Forwarded-For:line, isunknown, never the client-written6.6.6.6; - the proxy sent only the forwarding header Brace was not told to read (say only
Forwardedwhile the app readsX-Forwarded-For). Brace also logs one warning namingTrustedProxies.useForwardedHeader().
It is never the proxy's own address in those cases. Returning the proxy's address would let a
client who can malform the header pass for the proxy: an allowlist that admits 127.0.0.1 or
the proxy's LAN address would admit them, and they would get a second per-IP rate-limit budget.
What the sentinel means to each consumer:
- Address allowlists must fail closed on it.
unknownis not an address, soTrustedProxies.isTrusted("unknown")is false and anequalsagainst a real address is false. A denylist (if (blocked.contains(req.ip()))) does not catch it: check for it explicitly if you keep one. RateLimiter.perIpcounts everyunknownrequest in one shared bucket, so they are limited together, not exempt.- Analytics and logs record the string as it is.
A trusted peer that sends no forwarding header at all (a health check from the proxy itself, a
process on the proxy's host) is the client, and req.ip() is its address. A request from a peer
that is not a trusted proxy is always the socket address.
Repeated Cookie lines are joined (with ; ) into one list on every request and WebSocket
upgrade, and a cookie name that appears twice resolves to its first occurrence on both.
Brace uses the request's host to tell production from local development (the Secure
attribute) and to recognise same-origin WebSocket upgrades. nginx's default proxy_pass
replaces Host with the upstream address, so every request arrives as Host: 127.0.0.1:8080
— which looks exactly like a developer's machine. Symptoms: session cookies without Secure,
and every browser WebSocket rejected with 403. Brace logs a one-time warning when it sees the
pattern (a loopback Host from a browser on an https:// page), and uses that browser signal
to set Secure where it can, but requests without an Origin/Referer can't be recognised.
Fix the proxy:
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host; # don't pass a client's X-Forwarded-Host through
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /live { # each WebSocket path
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
}app.trustedProxies("127.0.0.1", "::1"); // nginx on the same hostCaddy's reverse_proxy already passes Host through and sets X-Forwarded-*; configure
trustedProxies so they are honoured. Load balancers that must rewrite Host should send
X-Forwarded-Host instead.
Configure session cookie security with SessionOptions:
// Secure defaults for production
app.sessions(SessionOptions.secure("your-secret")
.maxAgeDays(14)
.sameSiteLax());
// Custom configuration
app.sessions(SessionOptions.of("your-secret")
.secure(true) // HTTPS only
.httpOnly(true) // No JavaScript access
.sameSiteStrict() // Strict CSRF protection
.maxAgeDays(30) // 30-day expiration
.domain(".example.com") // Share across subdomains
.path("/app")); // Restrict to path| Attribute | Default | Purpose |
|---|---|---|
HttpOnly |
true |
Prevents JavaScript access (XSS mitigation) |
Secure |
resolved per request | HTTPS only — on for every non-loopback request (see below) |
SameSite |
Lax |
CSRF protection (Strict, Lax, or None) |
Max-Age |
session | Cookie lifetime (use maxAgeDays() to set) |
Path |
/ |
Scope to specific path |
Domain |
none | Share across subdomains |
With no explicit .secure(...), Brace decides the Secure attribute per response:
X-Forwarded-Proto: httpsfrom a trusted proxy →Secureon. This wins outright, so a proxy that rewritesHostto the upstream still gets the attribute.- Otherwise, on unless the request's host is a loopback address (
localhost,127.0.0.0/8,::1). The host isX-Forwarded-Hostfrom a trusted proxy, elseHost. - A loopback host from a browser whose
Origin(orReferer) is anhttps://page on a real host is treated as production: that request was relayed by a TLS proxy rewritingHost. This signal can only addSecure, never remove it. See "Pass the realHostthrough" above for the proper fix.
Brace serves cleartext HTTP/1.1 and expects TLS to be terminated by a reverse proxy, so it
cannot read the scheme off its own connector. Before 0.1.8 the attribute simply defaulted to
false, which meant every app built the documented way — .sessions(secret) — shipped a
session cookie a network attacker could read off any cleartext request to the domain. A
fixed true would have been no better: it breaks every app and test suite on
http://localhost. Hence the per-request rule, which needs no configuration in either
environment.
An explicit .secure(true) or .secure(false) always wins. An app genuinely served over
plain HTTP on a real hostname must opt out, and startup logs a warning when it has:
app.sessions(SessionOptions.of("secret").secure(false));An attacker cannot use the Host header to strip Secure from someone else's cookie: the
header they control is on their own request, and the Set-Cookie it shapes comes back to
them.
app.sessions(SessionOptions.secure("secret")
.maxAgeDays(14)
.sameSiteLax());This sets: HttpOnly=true, Secure=true (explicitly, regardless of request),
SameSite=Lax, Max-Age=1209600 (14 days)
Any response Brace attaches a session Set-Cookie to is sent private. With no
Cache-Control it gets Cache-Control: private. With one set by the handler or an
after-middleware, public is rewritten to private, and private is added in front when the
value has neither private nor no-store (max-age=600 becomes private, max-age=600; so
does s-maxage=600, which a shared cache then ignores); the other directives are kept. The
value is parsed into directives, so only a bare private or no-store directive counts: one
of those words inside a quoted argument (x="no-store", no-cache="private") or the qualified
form private="set-cookie" does not, and private is still added. A
response carrying a session cookie is per-user by definition — without this it is
heuristically cacheable, or explicitly storable, and a shared cache (e.g. an nginx recipe that
force-caches everything under /static/) would replay user A's cookie to every user.
Response header names are case-insensitive in Result: res.header("cache-control", ...) and
res.header("Cache-Control", ...) are the same header, and the second write replaces the
first. (Before 0.1.11 they were two entries; Brace checked one spelling and the other reached
the wire, so a lowercase cache-control: public rode out with the session cookie.) Only ASCII
letter case is folded, and res.header(name, value) throws IllegalArgumentException for a
name that is not an HTTP token (empty, or with a space, a colon, a control character or any
non-ASCII character), so a look-alike name (a Unicode hyphen in Cache-Control, the Kelvin
sign U+212A for K) is refused instead of reaching the wire or standing in for the real
header. Brace does
not strip CDN-Cache-Control, Surrogate-Control or Expires from a cookie-carrying response
outside a guarded static mapping or an access rejection, so don't set those app-wide on
responses that can carry a session.
The riskiest shape is a session-mutating middleware whose path pattern covers static
prefixes — for example a lastSeen-touch guard on /*. Every static file response then
carries a fresh session cookie. The private default makes that safe for spec-compliant
caches, but prefer scoping such middleware to application routes (/app/*) rather than
/*, and never configure a proxy to ignore response headers for paths a session
middleware can touch.
A static mapping with access requirements never sends anything a shared cache may store: a
served file is private, no-cache and every other response under it is no-store, with or
without a session cookie (see
Static mappings are covered too). Access rejections are
no-store everywhere (see Access rejections are never cached).
A page-cached route stores one rendered response per key and serves it to every visitor. The
key is the route pattern, its decoded path parameters, the method, the HX-Request variant, and
the query params and headers the route declares with .vary(...) and .varyHeader(...) (a param
given twice keys on all its values). A cached handler must depend only on those. Anything else
it reads (another query param, req.url(), a header such as Accept-Language, a cookie,
req.ip(), the body) can differ between visitors, and whatever the first visitor sent is replayed
to the rest for the TTL: ?msg=<b>PWNED</b> on an undeclared param becomes everyone's page. In dev
mode Brace logs such a read once per route, and under Brace.test() it throws, so a test of the
route fails; production does no checking. A read of req.path() (the raw, undecoded path, also
behind req.url() and req.urlWith(...)) is reported the same way, because one key covers
several spellings of a path: /p/! and /p/%21 are both in normal form and decode to the same
parameter. Read path parameters with req.pathParam(...) in a cached handler. req.method() is
not recorded, and production checks nothing, so both are also covered structurally: a HEAD is
never stored (it may be served an existing GET entry), and a request whose raw path is not in
RFC 3986 normal form (an escaped unreserved character such as /p/%62 for /p/b, lower-case hex,
raw non-ASCII) is rendered but never stored, so a crafted spelling cannot choose the page served
at the normal URL. Paged links built in a cached handler are the exception that is safe by
construction: they link back to the same route, and they copy only the declared vary params
(in every mode), so ?ref=evil.example on the first request is not in the stored links.
Some inputs are refused outright rather than trusted to the handler: a request with
Authorization, HX-Target, HX-Trigger, HX-Trigger-Name, HX-Boosted or HX-Prompt is
served by the handler without reading or writing the cache, unless the route declares that
header with .varyHeader(...). HX-Request is keyed as absent or exactly true; any other value
(1, True) bypasses the cache, so a handler testing req.hasHeader("HX-Request") cannot store
its partial under the full-page key. A declared header's value enters the key as its SHA-256
digest, so varyHeader("Authorization") never puts the credential in brace_cache.cache_key. A
response that sets a cookie is never stored (it is returned with its Set-Cookie intact). Only 2xx
responses are stored, and a response carrying the visitor's CSRF token or flash is not.
Page entries are kept apart from the app's own cache entries (keys starting brace:page:, which
set, getOrSet and delete refuse for app keys): on Postgres they have their own row cap
(10,000 by default), are trimmed least recently used first (written, or hit, recorded at most once
a minute per row) and are trimmed before app rows when the table is over its overall cap; in
memory a full cache evicts the page least recently hit (an approximate LRU), and a new page never
displaces an app entry, including while clear(), a tag clear or a prefix delete runs during a
page flood. A client minting pages (any declared vary value or path parameter)
therefore churns only the page cache, and pages nobody reads again go before the hot ones, so a
flood cannot lock the real pages out.
On the shared backend each value is stored as its class name plus Jackson JSON, so whoever can
write the brace_cache table chooses the class name a row carries. Brace never lets that choice
reach Jackson for an arbitrary class. A row is deserialized only when its class is:
- the exact class the caller asked for (
get(key, Rule.class)for aRule), always allowed; - a class this process has itself stored;
- a built-in JDK container or value (
ArrayList,LinkedList,HashMap,LinkedHashMap,TreeMap,HashSet,LinkedHashSet,TreeSet,ArrayDeque, theList.of/Map.of/Set.ofandCollections.unmodifiable*/empty*/singleton*classes except the sorted unmodifiable wrappers, boxed primitives,String,BigDecimal,BigInteger,UUID, thejava.timevalue types, and arrays of these), which Jackson rebuilds without running app code; - or a class registered with
cache.allowType(...).
A row whose body does not rebuild (Jackson throws, checked or not: a SingletonList row holding
two elements), or rebuilds as something other than the type the caller asked for (an
unmodifiableSortedSet comes back as a plain unmodifiable set), is a miss, never an exception
from get/getOrSet.
Anything else (an app class read through Object, an interface or a base class, or by
getOrSet, on an instance that has not stored it) is treated as a miss and logged at WARN once
per stored class and requested type. A miss on security state fails open: after a deploy, or on
a node that only reads, cache.get("denylist", Set.class) for an app-defined set type would see
nothing. Read security state with its concrete type, or register the class at startup on
every instance with cache.allowType(MyType.class). Register only plain data classes (records,
POJOs whose constructors and setters only assign): a registered class can be named by any row.
maxUploadSize bounds every request body, not just multipart uploads: a non-multipart
body (JSON, form post, raw bytes) larger than the limit is rejected with 413 Payload Too Large before the handler runs, and multipart parsing enforces the same cap. Configure it
to prevent DoS:
app.maxUploadSize("10M"); // 10 megabytes (default)
app.maxUploadSize("50M"); // 50 megabytesSince 0.1.8 the body is read after before-middleware runs, so a rate limiter or auth
guard can shed a request before its bytes are buffered. A guard that returns a result wins
over the 413; middleware that reads req.body() itself (a webhook signature check) still
triggers the read at that point.
An oversized upload is a client error: it returns 413 and deliberately records no
framework error. Before 0.1.10 the Content-Length fast-reject ran only for non-multipart
bodies, so an oversized multipart upload reached Jetty's own cap and surfaced as a 500
— which meant any unauthenticated client could flood the error store and the regression
notifier just by POSTing large files.
maxUploadSize counts the bytes as received: a gzip-encoded request body is not inflated
(see Response Compression), so it can't expand past the cap.
Multipart parts over uploadMemoryThreshold (default 1MB) are written to a temp file
rather than held in the heap, which bounds the memory an upload can consume but introduces
a file on disk holding untrusted content:
- The spill directory (
app.uploadTempDir(Path), default${java.io.tmpdir}/brace-uploads) is created owner-only (700) rather than under the ambient umask, and the files inside it are created owner-only by the JDK. - Spill files are deleted when the request ends — on every exit path, including 413s, CSRF 403s, thrown 404s and 500s. A missed path would not be a leaked file but an unbounded disk fill drivable by any client.
- A hard kill (SIGKILL, OOM, container eviction) skips cleanup, so startup sweeps files older than six hours. The sweep does not follow symlinks, so a symlink planted in the directory cannot turn it into an arbitrary-delete primitive.
- An
UploadedFileis only valid for the duration of its request. Save it, or push it toStorage, before the handler returns.
Budget disk accordingly: the worst case is concurrent uploads × maxUploadSize. This
trades a heap-exhaustion failure mode for a disk one, which degrades far more gracefully
(writes fail, the app keeps serving) but is still a resource an attacker can consume.
- Validate file types: check the extension against what you accept.
file.contentType()is whatever the uploader's browser (or script) claimed, so never trust it as the type - Scan for malware: Use external virus scanning for untrusted uploads
- Store safely: Don't use user-provided filenames directly
- Serve as untrusted: an uploaded
.htmlor.svgserved inline from the app's origin runs its script there (stored XSS). See Serving uploaded files - Limit concurrency: upload concurrency now consumes disk rather than heap — cap it at the proxy if untrusted clients can reach an upload endpoint
// DON'T: Use user filename directly
String key = "uploads/" + file.filename(); // ❌ Unsafe
file.saveTo(uploadDir.resolve(file.filename())); // ❌ Unsafe
// DO: Generate safe keys and names
String key = Storage.safeKey("uploads", file.filename()); // ✅ Safe
file.saveTo(uploadDir, file.safeFilename()); // ✅ SafeStorage.put, delete, and url reject keys containing ./.. segments or a leading /
outright: the SigV4 canonical URI and the request URL are built from the same unnormalized
string, so a traversing key would have been validly signed for the path it escaped to.
Storage.safeKey and UploadedFile.safeFilename() also neutralize an extension a browser or
server could execute: markup (html, htm, xhtml, shtml, mht…), svg/svgz,
xml/xsl/xslt/xsd, feeds (rss, atom, which browsers render as XHTML), js/mjs/es/
css/wasm/swf/htc/hta, and server-side scripts (php, phtml, asp, jsp, cgi,
pl, py…), in any case, and the same before a compression extension (x.svg.gz, which nginx's
gzip_static would serve for x.svg). safeKey replaces it with bin (u/<uuid>.bin);
safeFilename() turns each such extension's dot into _ wherever it is in the name and appends
.bin when it was last (page.html → page_html.bin, a.php.png → a_php.png, since some
servers run a handler for an extension anywhere in the name). Trailing dots and spaces are
dropped first. This is defense in depth for whatever serves the files by extension; the serving
rules below are the fix.
Storage.put(key, bytes, contentType) and put(key, path, contentType) store the type you pass.
Never pass file.contentType(): the uploader chose it. Use put(key, uploadedFile), which types
the object from the key.
Static directory. Register an upload directory as untrusted:
app.staticFiles("/assets", "public").publicFiles(); // your files
app.staticFiles("/uploads", "/var/app/uploads", StaticFiles.UNTRUSTED) // users' files
.access(Access.session("userId", "/login"));UNTRUSTED decides how a file is served; the access declaration decides who gets it, and every
mapping needs one (see Static mappings are covered too).
.publicFiles() on an upload directory means anyone who can guess or enumerate a name can fetch
the file: choose it only for uploads that are meant to be public, such as avatars. A static
mapping can only ask "may this user fetch from this directory"; when the answer depends on the
file, serve it from a handler (below).
In UNTRUSTED mode:
- The
Content-Typecomes from an allowlist by extension: raster images (png, jpeg, gif, webp, avif, bmp, ico), PDF, plain text, CSV, JSON, office documents, zip/gzip/tar, common audio and video. Anything else,.html,.svg,.xmland.jsincluded, isapplication/octet-stream. - Everything except a raster image is sent with
Content-Disposition: attachment, so following a link to it downloads it instead of rendering it. SVG is not a raster image. PDF is an attachment too: viewers that run PDF JavaScript differ, and the safe default is a download. - Every response carries
Content-Security-Policy: sandbox(no script, opaque origin, even if a browser renders it anyway) andX-Content-Type-Options: nosniff. The sandbox is sent as its own header, so an app CSP set bySecurityHeadersdoesn't replace it.
Images still render in <img>, and audio/video still play in <audio>/<video>; those ignore
Content-Disposition. staticFiles throws if an untrusted directory is inside a trusted one (or
the reverse), because its files would also be reachable through the trusted mapping; it compares
the paths as written and with symlinks resolved. A file a trusted mapping reaches that resolves
into an untrusted directory anyway (a link made later) is served as untrusted.
These headers are enforced as the response is written, after the handler and after-middleware, so
a Content-Type or Content-Disposition set later can't undo them, and a page-cache hit keeps
them. .untrusted() applies to 2xx responses; an error page is the app's own.
From a handler (an access check, a lookup by id), apply the same rules with
Result.untrusted():
app.get("/files/{name}", req -> Result.fileUnder(uploadDir, req.pathParam("name")).untrusted());
// doc looked up with db.findOwnedOr404(...); originalName is the uploader's filename
return Result.download(Path.of(doc.path), doc.originalName).untrusted(); // keeps the filenameS3. storage.put(key, uploadedFile) and putGenerated(folder, uploadedFile) ignore the
uploader's Content-Type. The object's type comes from the key's extension through the same
allowlist (application/octet-stream otherwise), and every object but a raster image is stored
with Content-Disposition: attachment. That matters even off the app's origin: a bucket or CDN
on a sibling subdomain shares the site for cookies. To store a type you checked yourself, pass it:
storage.put(key, file, "image/svg+xml").
Result.download(bytes, contentType, filename) is safe to call with a user-supplied name.
It drops any directory component and emits the RFC 6266 pair — an ASCII-safe
filename="…" plus filename*=UTF-8''… — so a name containing quotes cannot inject
Content-Disposition parameters, and non-ASCII names survive intact.
Http.multipart().field(name, bytes, filename) on the outbound side throws
IllegalArgumentException for a name or filename containing control characters, rather
than letting CR/LF terminate the part headers and forge extra parts in the request.
Every mapping declares its access: app.staticFiles(urlPrefix, directory).publicFiles() or
.access(...). start() refuses a mapping with neither, and defaultAccess(...) does not cover
mappings; see Static mappings are covered too. Prefer
.access(...) to a path guard for anything private: it is bound to the mapping, so it cannot
disagree with the path that is served.
A mapping serves GET and HEAD; every other method gets 405 with Allow: GET, HEAD. Its
directory must exist when the app starts, a URL prefix can be registered once, and two mappings
may share or nest directories only when their access is the same.
app.staticFiles(urlPrefix, directory) confines serving to directory. The check resolves
symlinks (toRealPath) before comparing, so a symlink under the served tree cannot serve a
file outside it — a lexical normalize() + startsWith check does not catch that, because
the traversal happens in the filesystem rather than in the path string.
Dotfiles and dot-directories (.env, .git/config, .htaccess, assets/.hidden/x) are never
served (404), whatever the mapping; the only exception is a leading .well-known/, so ACME
challenges and security.txt keep working. The check runs on the decoded path, so %2eenv
is refused too.
A static file is served only at its canonical spelling. Path guards (before("/files/private/*", ...),
a path-scoped after(...), a reverse proxy's location block) match the raw, still-encoded
request path, while the file lookup decodes it. Any second spelling of the same file would
skip a guard written for the first, so these get a 404:
- A percent-escape of an RFC 3986 unreserved character (
A-Z a-z 0-9 - . _ ~), in either hex case:/files/%70rivate/secret.txt,/files/a%7Eb.txt. Browsers,encodeURIComponentandUrl.tonever encode these. - An encoded or literal separator:
%2F,%5C,\. Jetty already answers these with a 400; the static handler refuses them as well in case URI compliance is relaxed. - A trailing slash or an empty segment:
/files/exact.txt/,/files/v2//app.js. The path that would be opened, written back out, has to equal the requested path character for character. (A trailing slash on a file was served before 0.1.11, past a guard on the exact path.) A directory is a 404 with or without the slash; there are no index files or listings. - A name that differs from the name stored on disk:
/files/PRIVATE/secret.txton a case-insensitive volume (macOS, Windows), or a decomposed (NFD) spelling of an accented name on APFS. Each requested segment is compared, case-sensitively, with the stored name.
Escapes that a canonical URL needs keep working: %20, UTF-8 bytes for non-ASCII names
(caf%C3%A9.txt, either hex case), and reserved characters (%26, %40, %3D, which may also
be written literally). Two consequences for guards: write the guarded path in unreserved
characters, because a guard pattern containing &, @, =, a space or non-ASCII can still
be reached by the other legitimate spelling of that character; and the case check relies on Path.toRealPath reporting
stored names, which it does on macOS and Windows; a Linux directory with the casefold
attribute is untested and may not be covered.
Symlinks that stay inside the served directory keep working. To serve a directory that
lives elsewhere, register it as its own mapping rather than linking it into the web root. A
directory users write to is registered UNTRUSTED (see
Serving uploaded files):
app.staticFiles("/assets", "public").publicFiles();
app.staticFiles("/assets/uploads", "/var/app/uploads", StaticFiles.UNTRUSTED)
.access(Access.session("userId", "/login"));When prefixes overlap, the longest one serves the request regardless of registration order, so
/assets/uploads/x is looked up in /var/app/uploads even though /assets was registered
first. (Before 0.1.11 the first registered prefix won, and the second mapping here was
unreachable.)
Brace sends no Server or X-Powered-By header. Requests that Jetty rejects before Brace's
handler runs (ambiguous URIs such as //x or %2e%2e segments, malformed requests) get a
plain-text reason phrase (Bad Request) with nosniff: no server version, and the request URI
is not echoed.
Static responses carry X-Content-Type-Options: nosniff, and — since 0.1.8 — the app's
after-middleware, so app.after(SecurityHeaders.defaults()) reaches them too. That matters
most when a static directory holds user-supplied content: those are exactly the responses
that need X-Frame-Options and a CSP.
Since 0.1.11 Brace gzips responses by default (app.compression(false) turns it off). The rules
are in CompressionHandler; the security-relevant ones:
- Request bodies are never inflated. A request with
Content-Encoding: gzipreaches the handler as the compressed bytes. Inflating would let a few KB on the wire expand pastmaxUploadSize(a gzip bomb), since the cap is checked against what the handler reads. - Only clients that send
Accept-Encoding: gzipget gzip, and every compressible response carriesVary: Accept-Encoding(merged withVary: HX-Requeston htmx responses), so a shared cache never hands compressed bytes to a client that didn't ask for them.
Compression makes a response's length depend on how much of it repeats. If a page reflects text the attacker chooses (a search term, a URL parameter) and contains a secret that is the same on every load, an attacker who can make the victim's browser send many requests and can see the encrypted response sizes on the network can recover the secret a character at a time. That is BREACH. It needs all of: HTTPS traffic the attacker can observe, a page that reflects their input, and a secret that is byte-identical across responses.
What Brace does about it:
- The CSRF token is masked per render, so it is never the same twice and compression has
nothing to match it against. This covers
${csrfField},${csrfToken}andCsrf.maskedToken(session). A page that printsCsrf.getToken(session)directly is not covered. - Session cookies are not in the body, so compression doesn't reach them.
What it doesn't cover, and what to do:
- Other secrets you render into HTML (an API key shown on a settings page, a personal access token, an invite link). Don't put long-lived secrets in pages that also echo request input. Show them once, or mask them the same way.
- Apps where BREACH matters more than bandwidth can turn compression off with
app.compression(false). A CDN in front of the app (Cloudflare, for example) re-compresses toward the browser regardless, so what an attacker on the browser's network sees is decided there; Brace's compression only changes the CDN-to-origin hop.
A WebSocket upgrade runs plain before(...) middleware, then the Origin check below, then
the route's access requirements (see Authorization); a rejection declines the
handshake. Before 0.1.11 the upgrade ran no guard at all, so a socket under a guarded path
accepted anonymous clients.
A socket is upgraded only at its registered path, spelled exactly. app.ws("/ws", ...) answers
/ws (with any query string); /x/../ws, /%77s and /ws;x get a 404 before any middleware
or guard runs. Jetty matches upgrades against the decoded path with dot segments resolved, so
without this check those spellings reached the socket while a reverse proxy matching the raw
request target saw some other path. The path given to app.ws(...) is therefore a literal, not
a pattern.
WebSocket upgrades are validated against the request's Origin. A handshake is not
subject to the same-origin policy, so without this an attacker's page could open a socket
to your app, have the browser attach the victim's session cookie, and hold an authenticated
socket for its lifetime (cross-site WebSocket hijacking).
- A cross-host
Originis rejected with 403. - A missing
Originis allowed: only browsers are required to send one, and only browsers are what the policy protects. Rejecting would break every non-browser client for no gain. - Hosts are compared without scheme or port, so TLS terminated at a proxy is fine. The app's
host is
X-Forwarded-Hostfrom a trusted proxy, elseHost— a proxy that rewritesHostto the upstream makes every same-origin socket look cross-origin (403, with a one-time warning). See "Pass the realHostthrough".
Declare deliberate cross-origin clients:
app.wsAllowedOrigins("https://studio.example.com"); // exact origin: scheme, host and port
app.wsAllowedOrigins("studio.example.com"); // bare host: any scheme or port
app.ws("/live", ctx -> new LiveHandler(ctx));Prefer the full origin: listing https://studio.example.com does not admit
http://studio.example.com, whose page a network attacker could inject into.
"*" disables the check — sound only if the socket carries no ambient authority, i.e. it
does not rely on the session cookie for authorization.
Do not rely on SameSite alone for this. The default SameSite=Lax session cookie does
make modern browsers withhold the cookie on a cross-site handshake, but that protection
disappears the moment an app calls sameSiteNone().
On Postgres, broadcast(room, message) reaches members on other instances through LISTEN/
NOTIFY. Postgres puts no permission on either: any role that can connect to the database can
NOTIFY any channel and LISTEN on any channel. Before 0.1.11 the channel was a fixed
brace_ws and payloads were plain JSON, so anyone with a database login (a reporting user, a
compromised neighbour app) could push frames to room members, which is script injection when an
app broadcasts HTML fragments for htmx. Two apps sharing a database also received each other's
broadcasts in same-named rooms.
Since 0.1.11:
- Every payload is signed. It is HMAC-SHA256 over the exact JSON body, with a key derived
(under its own label) from the session secret, or from
.opsSecret(...)when the app has no sessions. A receiver checks it in constant time and drops anything unsigned or wrongly signed. Payloads too large for aNOTIFY(over 7900 bytes, signature included) go through thebrace_ws_messagestable as before; the row is signed too, and the signed reference to it carries the row's content hash, so writing that table can't inject or swap messages (deleting rows can still suppress them, as it always could). - The channel is per app:
brace_ws_plus 16 hex digits of a hash of the key. Instances of one app agree on it; apps with different secrets never share one. The name is not a secret (it is visible to a superuser inpg_stat_activity), and nothing depends on it being one. - Replays are refused. Every payload carries an issued-at time and a random nonce. A
receiver drops a payload more than 60 seconds from its own clock, either way, and any nonce it
has already accepted. It also refuses anything issued before it started (its nonce memory
starts empty) or before the newest nonce it had to forget early under load, and the window's old
edge never moves back with the clock.
LISTENneeds no privilege, so a forger can also capture genuine payloads; without this, one captured message could be re-sent thousands of times to flood a room. Instances' clocks must agree to well within 60 seconds (NTP does), and a payload that waits over 60 seconds in a backed-up listener is dropped rather than delivered late. - Rejections are counted, not shouted. Dropped payloads are logged as a
ws_broadcast_rejectedevent at most once a minute, with the reason and a count since the last line. - No secret, no start. A Postgres app with WebSocket routes and neither
.sessions(secret)nor.opsSecret(secret)failsstart()with a message naming both. There is no per-process fallback: a random key would put each instance on its own channel and silently end cross-instance delivery.
The secret must be identical on every instance. Instances with different secrets (a rolling deploy that changes it, or one that mixes 0.1.10 and 0.1.11) don't see each other's broadcasts until they all match; nothing is delivered wrongly, but members on the other side miss messages.
The signature authenticates the sender as an instance of this app. It does not decide who may
read a room: joining one is still an authorization decision the handler makes before
ctx.join(room).
Protect endpoints from abuse with rate limiting:
// Per-IP rate limiting (`/api/*`: the bare `/api` pattern matches only the literal path /api)
app.before("/api/*", RateLimiter.perIp(100, "1m"));
// Per-client rate limiting: requests without the header are limited per IP (see below)
app.before("/api/*", RateLimiter.perKey(
req -> req.header("Authorization"),
1000,
"1h"
));
// Login attempts per account: count submissions only (not views of the login page), and
// normalize the username so "Alice", "alice" and "alice " are one account
var loginLimit = RateLimiter.perKey(req -> {
var username = req.formParam("username");
return username == null ? null : username.strip().toLowerCase(Locale.ROOT);
}, 5, "15m");
app.before("/login", req -> "POST".equals(req.method()) ? loginLimit.handle(req) : null);Key the limiter on the value the handler uses. req.formParam(...) reads the request body
only, and so does req.form(...) on POST, PUT, PATCH and DELETE: a field in the query
string never fills a form field on those methods. (Only GET and HEAD forms bind from the
query string.) A limiter keyed on formParam("username") therefore counts exactly the username
the login handler checks; POST /login?username=victim with no username in the body is counted
in the client's missing-key bucket and binds no username.
Rate-limit keys extracted from requests (usernames, tokens, IP addresses, custom headers) are normalized before use:
-
Null or blank extractor result → a missing-key bucket per client address (
(none):plus the address, an IPv6 client's /64, with the limiter's own limit and window). A request with a missing header or form field is limited exactly asperIpwould limit it, rather than silently bypassing the limiter, and keyless requests from one address never use up another's budget (an earlier design counted them all in one global bucket, so five visitors viewing a page the limiter covered locked out the sixth). The bucket keys cannot be produced from a request, so a client that sends the literal value(none):203.0.113.9gets its own bucket and cannot drain that address's. Where a missing key genuinely means "nothing to limit", opt out explicitly, and bound those requests some other way (here, per IP):app.before("/api/*", RateLimiter.perIp(300, "1m")); app.before("/api/*", RateLimiter.perKey(req -> req.header("X-Api-Key"), 1000, "1h") .exemptMissingKey());
Don't register a key limiter on a path whose page views carry no key (a
GET /loginwith no username) without restricting it to the submissions, as the login example above does: otherwise each view uses up one of that visitor's keyless requests, and a visitor who reloads the pagelimittimes is locked out of it. Dev mode logs a warning, once per limiter, the first time a key limiter counts a keylessGETorHEAD. -
Surrounding whitespace is stripped, so
"victim "and"victim"are one bucket. Case is not folded: tokens and API keys are case-sensitive. When the key is an identity that is case-insensitive (a username, an email address), lower-case it in the extractor, as above. -
Keys longer than 64 characters → SHA-256 hex digest (always exactly 64 chars). Long user-controlled values (e.g. bearer tokens, forged headers) would otherwise create unbounded storage — millions of bytes of map entries locally, or arbitrarily large rows in
brace_counters. Hashing caps the key size while preserving the collision-resistance needed for correct bucketing. -
Keys containing a control character → SHA-256 hex digest too. Postgres refuses a NUL in a text parameter, so a raw
username=a%00key would otherwise fail every shared-counter write.
The cap is applied before any prefix or window-slot decoration, so it holds equally in per-process and shared (Postgres) modes.
perIp keys an IPv6 client on its /64. A site is normally given at least a /64, so one client
can rotate through billions of source addresses; keying each address separately would give it a
fresh budget per request. IPv4 clients (and IPv4-mapped IPv6 addresses such as ::ffff:203.0.113.7)
are keyed on the full address. Clients that share a /64 share a budget.
A limiter's memory is bounded. Each limiter tracks at most maxKeys keys (default 100,000)
plus at most maxKeys per-address overflow buckets and one last-resort bucket: at most
2 × maxKeys + 1 tracked entries per instance, however many distinct keys clients send.
(Concurrent requests can put a table a few entries over for a moment, at most one per request
in flight.) Change the cap per limiter with .maxKeys(n), e.g.
RateLimiter.perIp(100, "1m").maxKeys(500_000). Counting all of it, one limiter holds at most:
- the tracked entries above,
2 × maxKeys + 1; - on Postgres, the flush queue of keys counted since the last flush, which can still hold keys
evicted from the tables: at most
2 × maxKeys + 10,016entries (dirtyBound()), reached only while flushes are failing; - after a shared-counter database error, the per-process fallback tables, which fill like the
tracked ones (another
2 × maxKeys + 1at most) and empty as their windows end; - on Postgres, two generations of the evicted-key filter, 4 bytes per
maxKeyseach (at least 8 KB, at most 4 MB each).
So in the worst case, a long database outage under a key flood, about 6 × maxKeys + 10,018
entries of a few hundred bytes each plus up to 8 × maxKeys bytes of filter.
Once the key table is full (a warning is logged, at most once a minute), a request for a key the limiter is not tracking is handled in this order:
- It takes the place of a tracked key that is under its limit: the least recently used of a small sample, by a per-limiter sequence number, so a key in active use is not the one chosen while an idler one is in the sample.
- A key at or over its limit is never forgotten before its window ends, so a flood cannot unblock a client that is being limited.
- When the sample holds only such blocked keys, the request is counted in an overflow bucket
for its client address (
ipBucket(req.ip()), an IPv6 client's /64), with the limiter's limit: that address getslimitrequests per window across all its untracked keys. Overflow buckets are replaced by the same rule (under its limit: replaceable; at its limit: kept). - When the overflow table too holds only buckets at their limit, the limiter is saturated
and
onSaturation(...)decides (below).
What forgetting a key costs. It differs by mode:
- Postgres (shared counters). Nothing is lost fleet-wide. The key's
brace_countersrow is never deleted by an eviction, and a count the instance had buffered for it is still written at the next flush. When the key comes back, the instance reads its fleet count with one single-row statement before judging the request, provided two things hold: the instance still recognises the key as one it evicted (a pair of rotating Bloom filters remembers at least the lastmax(2,048, min(maxKeys, 1,048,576))keys it evicted, with under 1% false positives however long the window), and the limiter has made fewer than 50 such reads in the current second. Otherwise the key is counted as new and its fleet count arrives with the limiter's next batched flush, the same lag every key has: a key the fleet has blocked is admitted by that instance at most one flush batch (limit / 10requests by default, seerateLimitBatchDivisor) before it is refused, plus any requests that arrive while another thread's flush is still running, and from then on it stays blocked there. The read budget is what keeps a flood of fresh keys from putting a database round trip on every request. One caveat: on an instance whose key table is full of keys at their limit, a key it is not tracking gets no entry of its own (step 3 above), so a key the fleet has blocked is counted there in its client address's overflow bucket: it gets at mostlimitrequests per window from that address, shared with that address's other untracked keys, rather than being refused as a key. That is the documented last-resort step, and it takes a flood that pins the whole table. (Counts buffered but unwritten can be lost only while database writes are failing, and during an outage every instance counts on its own.) - Per-process counting (no shared database). The forgotten key's count so far, fewer than
limit, is gone: if it returns it starts again from zero. A client that wants extra attempts at one key must therefore fill the table with fresh keys and keep it turning over; with the default cap that is on the order of 6,000 requests for each time the target key is forgotten, buying fewer thanlimitextra attempts. That is the price of bounded memory; aperIplimiter in front caps how fast one address can turn the table over.
Saturation, and what it costs an attacker to get there. With the documented login limiter,
perKey(…, 5, "15m") and the default cap:
- Pinning the key table takes 100,000 keys driven to their limit: 600,000 requests in one 15-minute window, about 670 requests a second, from any number of addresses. From then on a new key is counted against its client address (step 3), so each address still gets 5 attempts per window, and keys already tracked are unaffected.
- Pinning the overflow table as well takes 100,000 distinct client addresses (IPv4 addresses or IPv6 /64s, e.g. two /48 allocations), each driven to its limit: another 600,000 requests per window. Sustained, that is about 1,300 requests a second from 100,000 networks.
A saturated limiter cannot count a request for a key it is not tracking from an address it is not tracking. You choose what happens to those requests; each choice hands that attacker something:
onSaturation(...) |
Such a request is | What the attacker gains while they sustain the flood |
|---|---|---|
RateLimiter.Saturation.FAIL_CLOSED (default) |
counted in one last-resort bucket with the limiter's limit, shared by all of them, so nearly all are refused with 429 | A lockout: clients the limiter is not already tracking (in practice, anyone who has not just used the endpoint) cannot use it. No request goes uncounted. |
RateLimiter.Saturation.FAIL_OPEN |
let through uncounted | Unlimited attempts at any key the limiter is not tracking, which for a login limiter is unlimited password guessing against accounts of their choice. Nobody is locked out. |
// The default, spelled out:
app.before("/login", RateLimiter.perKey(keyFn, 5, "15m").onSaturation(RateLimiter.Saturation.FAIL_CLOSED));
// Availability over the limit, for an endpoint where an uncounted request is cheap:
app.before("/api/*", RateLimiter.perIp(1000, "1m").onSaturation(RateLimiter.Saturation.FAIL_OPEN));In both modes a tracked key is still counted and a blocked key stays blocked, and a warning is
logged at most once a minute while the limiter is saturated. The default is FAIL_CLOSED
because the limiter exists to bound attempts, and an attacker with this much traffic can degrade
availability in other ways regardless. Either way, raise the cost: a larger maxKeys raises both
figures in proportion (memory grows with it, a few hundred bytes per entry), and a perIp
limiter registered before the key limiter bounds how many of those requests one address can
contribute. Neither removes the trade-off; a limiter with bounded memory has to do something
with the request it has no room for.
brace_counters rows are bounded by time, not by the cap. A row is written for each key
counted in a window and removed only after the window ends (each instance sweeps expired rows
once a minute). A flood of fresh keys therefore holds up to one row per distinct key per window:
600 new keys a second against a 15-minute window is about 540,000 small rows at the peak, gone a
minute after their windows end. Rows are not deleted earlier, because an instance that has
forgotten a key cannot know the rest of the fleet has.
Eviction looks at a fixed number of keys under a per-limiter lock taken only on that full-table path, so no request scans a table.
Two limiters with the same type, limit and window share buckets on Postgres. The counter key
is built from the limiter's label (perKey(5/15m)), the only identity a limiter has across a
fleet, so on Postgres two such limiters count every key together, their missing-key and overflow
buckets included. In per-process mode each limiter object counts on its own. Give limiters on
different paths different limits or windows if they must be independent.
Cache keys get the same treatment in the Cache facade, on both backends: a key with a control
character, or longer than 512 UTF-8 bytes (a page path or vary value near the 8 KB URI limit
exceeds Postgres's index row limit), is stored as its first characters (up to 128, stopping at a
control character) followed by a SHA-256 digest of the whole key. This is invisible to callers;
tags still invalidate the entry, and deletePrefix still reaches it through the kept prefix.
A key (rate-limit or cache) with an unpaired surrogate is hashed too, from an encoding that
keeps it distinct: pgjdbc sends a lone surrogate as ?, so "a\uD800" and "a\uD801" were one
row on Postgres.
deletePrefix with a prefix that reaches past what a hashed key keeps readable (one containing a
control character, an unpaired surrogate or #sha256:, or longer than 128 characters) deletes the
keys stored as-is that start with the whole prefix, plus the hashed keys whose readable part is
exactly the prefix's readable part (every hashed key that starts with the prefix has that). So
deletePrefix("search:\u0001") and deletePrefix("search:#sha256:") no longer clear
search:alpha (they used to clear all of search:), but they do clear other hashed keys that
share the readable part, such as search:\u0002; a 200-character prefix clears hashed keys that
share its first 128 characters. Over-deletion is a cache miss, never a stale entry.
RateLimiter.perIp uses req.ip(), which respects trusted-proxy configuration. Without
app.trustedProxies(...), req.ip() returns the direct socket peer — headers are ignored. With
trusted proxies configured, Brace uses rightmost-untrusted semantics on X-Forwarded-For
(walking right to left, skipping trusted CIDR entries) so spoofed leftmost entries are ignored.
See the Trusted Proxies section for configuration. Configuring trusted proxies
correctly is a prerequisite for effective IP-based rate limiting — without it an attacker can
bypass per-IP limits by forging X-Forwarded-For.
Because this misconfiguration is silent (behind a proxy or CDN every request shares the proxy's
address, so a per-IP limit quietly becomes site-wide), Brace.start() logs a warning when a
RateLimiter.perIp middleware is registered without app.trustedProxies(...). Ignore the
warning only if clients genuinely connect to the app directly.
When Postgres is in use (multi-server mode), every rate-limited request increments a shared
counter. If the shared counter fails (connection pool exhausted, DB outage), Brace falls back
to per-instance counting for that request rather than returning a 500 or admitting the request
without any check. During an outage the effective limit across a fleet of N instances becomes
approximately limit × N, so brief over-admission is possible — this is intentional: the
alternative (turning every rate-limited endpoint into a 500) is worse. A warning is logged at
WARN level for each request that falls back.
Buffered counts are written in statements of at most 5,000 keys (Postgres refuses a statement with more than 65,535 parameters). A statement the database refuses with a data error (SQLState class 22 or 54: a key it cannot store) is split in half, and the halves again, until the refused key is isolated; that key's buffered count is dropped with a warning instead of failing every later flush, at a cost of a few dozen statements rather than one per key. Any other failure (the database unreachable, SQLState class 08, 53 or 57, or an error that is not about the data) restores every count not yet written and retries after a one-second back-off. A flush runs on the request that filled the buffer, so it has a 2-second budget: it stops between statements once the budget is spent, and each statement carries a JDBC query timeout for what is left of it, so a statement stuck behind a lock or a slow database is cancelled rather than holding the request. JDBC timeouts are whole seconds, rounded up, so the hold is bounded at about the budget plus one second; what was not written is kept for the next flush. (Waiting for a free pooled connection is bounded by the pool's own connection timeout, not by this budget.)
- Configure trusted proxies first (otherwise IP-based limiting is ineffective — see above)
- Use different limits for different endpoints:
- Login: 5 attempts per 15 minutes
- API: 100-1000 requests per hour
- Anonymous: 10 requests per minute
- Combine with authentication for logged-in users
brace new scaffolds a container setup meant to be deployed as-is:
Dockerfile. A Maven build stage, then a distroless Java 25 runtime: a JRE and nothing else, so no shell or package manager for an attacker to use. Both base images are pinned by digest, so a rebuild can't pick up a different image, and.github/dependabot.ymlproposes digest updates weekly. The process runs as uid 65532 (USER 65532:65532), and the app's files are owned by root, so the process can't modify its own code or config. TheENTRYPOINTis exec form:javais PID 1 and getsdocker stop's SIGTERM. JVM flags come fromJAVA_TOOL_OPTIONS, which the health-check JVM also reads: flags that bind a port, write a file or load an agent don't belong there unless theHEALTHCHECKis replaced by the platform's HTTP check..dockerignore. Keepsapplication.conf(the dev session secret),*.key(the ops private key),.envfiles andtarget/out of the build context. The image's config isapplication.conf.example, whose values all come from environment variables.compose.yaml. The reference deployment. The app container has a read-only root filesystem (/tmp, where uploads spill, is an in-memory tmpfs), drops every Linux capability, setsno-new-privileges, and publishes its port on loopback only, for a TLS-terminating reverse proxy in front. Postgres sits on aninternalnetwork with no published port, reachable only from the app. Secrets are required environment variables (${SESSION_SECRET:?…}), never values in the file.- Health.
GET /__brace/healthanswers200 okbefore routing and middleware, so an app-wide login guard or rate limiter can't fail it. It reveals nothing (no version, no database status) and isn't logged, counted or recorded by analytics. The image'sHEALTHCHECKpolls it withcom.larvalabs.brace.HealthCheck, since the image has no curl. - Listen address. Brace listens on every interface by default, which a container needs.
Outside one, with a reverse proxy on the same host, bind to loopback with
app.host("127.0.0.1").
Behind Traefik (Dokploy) or another proxy container, set TRUSTED_PROXIES to the proxy's own
address or its network's CIDR so req.ip() sees real clients; see
Trusted Proxies.
install.sh, brace self-update and the launcher's fetch of a project's pinned version download
code you then run, so they use https only, redirects included (file:// for local test
trees). Plain http:// in BRACE_RELEASE_BASE or BRACE_LATEST_URL is refused unless
BRACE_ALLOW_INSECURE_DOWNLOAD=1, which warns. Release zips are not signed yet; TLS to GitHub
authenticates them (see RELEASE.md, "Download integrity").
Ops endpoints (/ops/*) provide powerful observability and control. Secure them carefully.
Ops endpoints use public key authentication:
app.ops("authorized-keys").opsOrigins("https://app.example.com"); // origins: required outside devThe authorized-keys file contains public keys of clients allowed to access ops endpoints.
Clients mint a bearer token via POST /ops/auth (protocol v3): an Ed25519 signature over
"brace-ops-auth-v3\n" + origin + "\n" + publicKey + "\n" + timestamp + "\n" + nonce, where
the origin is the server the client means (https://app.example.com), the timestamp must be
within ±30 seconds of server time and the nonce is fresh random (16+ bytes, base64url) per
attempt. Binding the public key means a captured signature is only valid for the key that
produced it; the nonce makes each signed request single-use; the origin makes it valid only at
the server it names. The exact wire format is in docs/agent-ops-guide.md.
Each key has its own quota of remembered nonces: 5,000 per two minutes, or less when there are more than 20 authorized keys, so that every key's share fits inside the overall 100,000. One key, even a read-scoped one, cannot fill the memory and block other operators' logins, and no group of keys can either. A key over its quota gets a 401 saying so. What "single-use" covers, across instances and restarts, is set out under "Replay suppression" below.
The signature is bound to a server. The CLI reads the server's URL from the committed
.brace file, so a pull request that points ops.prod.url somewhere else could collect a fresh
signature and relay it to the real server within the time window. The server accepts a v3
signature only for an origin listed with app.opsOrigins("https://app.example.com") (or the
BRACE_OPS_ORIGINS environment variable, comma-separated), compared exactly: scheme, host and
port. The request's Host and X-Forwarded-Host play no part, because the client relaying a
signature chooses those: an app reachable directly, or a proxy that passes a client's
X-Forwarded-Host through to an app that trusts the proxy, would let it claim any host. Every
mode except dev (including an unset brace.mode, as in older scaffold Dockerfiles) refuses to
start with ops on and no origin configured. In dev mode and the test harness, with none set, the
origin's host must match the request's host instead, which is no defense against a client that
can reach the app directly.
The CLI keys its token cache by origin (and checks the origin stored in the cache file), so a
token minted for one server is never sent to another; it refuses an ops URL that is more than an
origin (user info, path, query); and it warns when a project's ops URL changes from the last
server it logged in to (remembered in ~/.brace/ops-origins.json; a best-effort hint, not a
control: a new clone or a new ops.env won't trigger it).
Protocol v2 is removed as of 0.1.11: it signed no origin, so a signature was good at any server. A v2 body gets a 401 naming the cause; upgrade the CLI with the server.
Protocol v1 is removed as of 0.1.8. It signed the timestamp alone — not bound to the key, no nonce — so a captured request was replayable verbatim inside the ±30 s window to mint a fresh token at the key's full scope ceiling. A v1 body now gets a 401 naming the cause; clients older than 0.1.7 must be upgraded.
Caching. Every /ops/* response carries Cache-Control: no-store. This matters for the
cookie channel specifically: RFC 9111 already forbids shared caches from storing a response to
a request carrying Authorization, but no such rule covers a cookie-authenticated GET, and
/ops/dashboard shows one operator's view of the app.
The __brace_ops_session cookie is scoped to Path=/ops, so an operator credential is not
attached to every application request where any handler could read it via req.cookie(...).
Credential channels (general endpoints). All ops endpoints except the browser exchange handoff accept credentials through exactly two channels:
Authorization: Bearer <token>header — the standard channel for the CLI and scripts.- The
__brace_ops_sessionhttpOnly cookie — set by the browser exchange flow below, and the only credential the dashboard and analytics pages use.
?token= query-parameter credentials are not accepted on general ops endpoints. Tokens in
URLs leak into proxy access logs, browser history, and the Referer header of outbound links.
Pass credentials via the Authorization header or the session cookie.
Browser exchange flow. The brace dashboard CLI command calls POST /ops/auth/login-token
(bearer only: the session cookie is refused there), receives a short-lived (60s, never past the
bearer's own expiry), scope-capped login token, and opens the
browser at /ops/auth/exchange?token=<loginToken>. The exchange endpoint is the only place
?token= is accepted — it is the browser-redirect handoff, and there is no other channel that
can carry a credential into a plain GET redirect. On success, the server sets an 8h httpOnly
session cookie and redirects to the dashboard. The exchange response carries
Referrer-Policy: no-referrer and Cache-Control: no-store so the token-bearing URL is
not forwarded to any outbound link and is not stored in proxy or browser caches.
Replay trade-off (exchange). The login token is stateless and HMAC-verified — no server-side store is needed, so the exchange works behind a load balancer even if the redirect hits a different instance than the one that issued the token (B5). Within the 60s TTL the same login token can be exchanged more than once; single-use would require fleet-wide shared state that ops can't assume. The TTL is kept very short to limit the replay window.
Replay suppression (auth). A sign-in request that a server has accepted must not be accepted again. Two layers do that, and which guarantee you get depends on whether the app has a database:
- With a database (
app.database(...)): each accepted nonce is also recorded in the framework'sbrace_counterstable (a 64-character digest and an expiry two minutes on; no migration, no configuration). The record is shared by every instance and outlives the process, so an accepted request is refused by every instance and after any restart or deploy. Nothing is refused after a start. If the write fails (database down), sign-in still works and the rules of the next bullet apply until it succeeds again. A sign-in never waits on the database: the write, waiting for a pooled connection included, is given 2 seconds and then counts as failed (its statement carries a query timeout so it does not linger), and after a failure the database is not tried again for 10 seconds, so every sign-in during an outage is answered at once. A write that completes after its 2 seconds records only that request's nonce, which the instance already remembers and the CLI never reuses, so it cannot refuse a later sign-in. Two instances recording the same nonce at once is a replay on every database: the one that loses the race (a unique-key violation) refuses it. - Without a database, or while it is unreachable: accepted nonces are remembered in each instance's memory only. A replay to the same instance is refused. A restart empties that memory, so for the first minute after a start the server refuses any sign-in whose timestamp is earlier than 30 seconds after it started: the previous process accepted only timestamps within 30 seconds of its clock and had stopped before this one started, so everything it accepted falls in that range. The cost: a sign-in during the first 30 seconds after a start (up to 60 for a client whose clock runs behind) gets a 401 that names the restart and says to retry. Dev mode and the test harness skip this window. Residual in this mode: behind a load balancer a request accepted by one live instance can be replayed against a different instance until its ±30 s timestamp window closes; that includes the old instance of a rolling deploy while both run.
In both modes the checks run only after the signature and the origin have been verified, so a caller without an authorized key learns nothing from them, and a request no server ever accepted (the client's connection failed before delivery) is, like any bearer of a valid signature, good once within its 30 seconds. HTTPS is what keeps an attacker from observing a request in the first place; see the recommendations below. The old v1 and v2 protocols are removed (see above).
Residual: a future-dated request no server has accepted. The timestamp may be up to 30 s ahead of the server's clock, and a request is good until its timestamp is 30 s old, so a request signed by a client whose clock runs fast stays presentable for up to a minute after it was made. One dated further ahead is refused as stale without its nonce being recorded, so it becomes acceptable once the server's clock catches up to within 30 s of it. Either can be presented once, by whoever holds it, when it is within the window; the replay guarantee above covers only requests a server has accepted. It requires capturing a request that was never delivered, or one refused for its timestamp, which HTTPS prevents.
Key revocation. Tokens are bound to the key that minted them. At startup the server takes
the fingerprints of the keys in ops-authorized-keys and rejects any bearer token, ops session
cookie or login token whose kid is not among them, or that has no kid, and caps every
token's scope at its key's current ceiling. Removing a key, or lowering it to scope:read, and
restarting or redeploying takes effect on its outstanding tokens immediately, although the token secret is derived from
the session secret and unexpired tokens (up to 24 h bearer, 8 h cookie) would otherwise survive
the restart.
The ops-authorized-keys format: every key line states its scope. The file is UTF-8 (a
byte-order mark at the very start is ignored), one key per line, in one of two forms:
KEY scope:read [label words ...] [# comment]
KEY scope:control [label words ...] [# comment]
scope:read allows status, logs, errors and the other read endpoints; scope:control allows
everything. Nothing is inferred: a key line with no scope token fails startup. (Until
0.1.11 such a line meant control, so KEY read ci-agent, KEY ci-agent read-only and
KEY (read) all quietly loaded as full-control keys.) The rules:
#at the start of a line, or after whitespace, starts a comment that runs to the end of the line. Blank and comment-only lines are ignored. (ci#1is label text: no whitespace before the#.)- The first token is the public key: the base64 Ed25519 key that
brace ops keypairprints. Anything that could never match a client's key fails startup with its own message: truncated or padded base64, a key of another type, an OpenSSHssh-ed25519 AAAA…line. - Exactly one of the remaining tokens is
scope:readorscope:control(scope:in lowercase, the value case-insensitive); the tokens may come in any order. - Any other token containing
:or=fails startup:scope: read,Scope:read,scope=read,--scope=read,role:read,scpoe:read,scope:read-only, or a second scope token. - Every other token is label text, including
control,ro,readandscope-ci: with the scope stated, a label is only a label. - A comment on a key line may not contain
scope:orscope=(KEY label #1 scope:readhas its scope inside the comment, where it would be ignored). Comment-only lines may say anything. - A key line may not contain whitespace other than space and tab (a no-break space joins two
tokens invisibly), a byte-order mark, an invisible control or format character, or a
look-alike of
:or=such as the fullwidth colon (scope:read). The error names the column and the code point.
Failures name the file and line number, never the key. The message for a missing scope reads:
Invalid ops authorized keys file ops-authorized-keys, line 3: the line has no scope. Every key
line must say scope:read (status, logs and errors only) or scope:control (everything). A line
without one used to mean control: add scope:control to keep that, or scope:read if the key was
meant to be read-only. Format, one of: KEY scope:read [label words...] [# comment] or
KEY scope:control [label words...] [# comment]. ...
brace ops keypair always writes the token (scope:control, or scope:read with
--read-only), as does the file brace new generates. A key listed twice keeps the lower
scope. A key must be written in its one canonical base64 spelling, as brace ops keypair prints
it: a spelling the decoder also accepts (missing = padding, or a last character that differs
only in bits the decoding ignores) fails startup, because keys are matched as text and a second
spelling would be a second entry with its own scope. Each key's fingerprint and scope is logged
at boot (ops.key). A token whose payload has no scope claim, or one the server does not
recognise, is treated as read, as is an unrecognised scope requested at /ops/auth.
/ops/dashboard and /ops/analytics are cookie-only. Their htmx polling and the CONTROL
buttons (resolve an error, clear the cache) send the __brace_ops_session cookie and nothing
else; no token is written into the page. Until 0.1.11 the dashboard embedded a 2-hour bearer
token (up to CONTROL scope) in hx-headers, so any script running on the app's origin in an
operator's browser could fetch('/ops/dashboard') (same-origin, so the cookie went along) and
read it out of the HTML. The httpOnly cookie can't be read by page script.
Each token works on one channel. Every ops token carries a type: bearer (issued to the CLI
by POST /ops/auth, accepted only in Authorization: Bearer), login (the 60-second handoff,
accepted only by /ops/auth/exchange), and session (the cookie the exchange sets, accepted
only as the cookie). POST /ops/auth/login-token takes only a bearer token. Before this, script
on the app's origin could post to it with the operator's cookie, read a CONTROL login token from
the response, use it as a bearer from anywhere, and mint the next one with it. A token without a
type (minted before 0.1.11) is refused; the CLI re-authenticates on the 401.
Cross-origin protection for cookie-authenticated changes. The ops routes are
.csrf(false), since the CLI posts with a bearer token. A mutating ops request
(POST/PUT/PATCH/DELETE) authenticated by the cookie must come from a page on the same
origin: Sec-Fetch-Site: same-origin when the browser sends it, otherwise an Origin whose
host and port are the ones requested. Anything else is refused with 403 {"error":"cross_origin_request"}
and audited. SameSite=Strict already keeps the cookie off cross-site requests, but not off a
sibling subdomain's: evil.example.com is the same site as app.example.com, so its form
post would carry the cookie. A bearer-authenticated request needs no such check, because a
cross-origin page can't set Authorization.
The ops Content-Security-Policy. Every response from a framework /ops route carries:
Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'
plus X-Content-Type-Options: nosniff, X-Frame-Options: DENY and Referrer-Policy: no-referrer, and any Access-Control-* headers the app's middleware added are removed (an app
CORS policy that reflects origins with credentials would otherwise let a same-site page read ops
JSON). The pages load their
JavaScript and CSS from /__brace/ops.js, /__brace/ops.css and /__brace/ops-analytics.css
and contain no inline script, event handler or style="" attribute. The headers are set at the
response choke point after the app's after-middleware, so they replace whatever policy the app
sets: a lax app policy can't weaken the ops pages, and an unusual one can't break them. The ops
policy is stricter than SecurityHeaders.strict() in every directive, so an app using strict()
loses nothing there.
What remains. An XSS on the app's origin still runs with the operator's ops session in the
same browser: it can't read the cookie or obtain a token, but it can drive same-origin requests,
including POST /ops/cache/clear with a valid Sec-Fetch-Site: same-origin. The cookie is
scoped to Path=/ops, which limits where it's sent, not who on the origin can trigger a
request. For high-value apps, serve ops from its own hostname (below), so that the app's origin
and the ops origin are different and the browser keeps them apart.
- HTTPS only: Never expose ops endpoints over HTTP
- Restrict at reverse proxy: Use IP allowlisting at nginx/Caddy
- Don't expose publicly: Ops endpoints should not be internet-accessible
- Rotate keys regularly: Implement key rotation for ops access
- Monitor access: Log all ops endpoint access
- Separate hostname for high-value apps: route
/ops/*only on a dedicated hostname (e.g.ops.app.example.com, reachable from the operator network) and refuse it on the public one. The ops cookie and pages then live on an origin where no application page, and so no application XSS, ever runs. Pointops.prod.urlin.braceat the ops hostname for the CLI.
# nginx config
location /ops/ {
allow 10.0.0.0/8; # Internal network only
deny all;
proxy_pass http://app;
}With a separate ops hostname (recommendation 6), the public server refuses /ops/ outright and
only the internal one proxies it:
server {
server_name app.example.com;
location /ops/ { return 404; }
location / { proxy_pass http://app; }
}
server {
server_name ops.app.example.com;
allow 10.0.0.0/8;
deny all;
location /ops/ { proxy_pass http://app; }
location /__brace/ { proxy_pass http://app; } # the ops pages' JS and CSS
location / { return 404; }
}app.analytics() counts page views on the server. Its security properties, and what to check
when you turn it on (full guide: analytics.md):
- No new public endpoint. Data comes only from requests the app already served; there is no
ingest URL for anyone to post fake events to. The viewing endpoints (
/ops/analytics,/ops/analytics/data,POST /ops/analytics/ignore) are ordinary ops endpoints:readscope,Cache-Control: no-store, the same two credential channels as above. - What's stored. Per view: time, day/hour, a 64-bit visitor hash, the path, the referring
host (or
utm_source/ref), device/browser/OS family and an optional country code. No IP, no user agent, no query string, no full referrer URL. The IP and user agent stay in memory for up to ~10 seconds until the next flush hashes them. - Visitor hash. SHA-256 over a random per-day salt, the host, the IP and the user agent,
truncated to 64 bits. The salt lives in
brace_analytics_saltsand is deleted 5 minutes after its day ends, after which a stored hash can't be matched to an IP, even by brute force over the IPv4 space. During the day, someone who can read the database and already has a candidate IP and user agent can test them against stored hashes. Treat database read access accordingly. - Daily summaries hold no visitor IDs.
brace_analytics_dailystores only per-day counts per page, source, device, browser, OS and country, and is kept indefinitely. The paths in it are the same redacted paths as the raw rows, so the advice below applies to it too. - Paths can carry secrets. Concrete paths are stored and shown on the dashboard, after two
redaction passes that reuse the error-store rules (see below): a route parameter with a
sensitive name (
Redactor.isSensitive, e.g.{token},{apiKey}) is stored as its placeholder, and a segment with a secret-shaped value becomes[redacted]. A short code under an ordinary name (/invite/{code}) passes both; mark such routes.analytics(false)or rename the parameter. - Bounded growth. Only matched routes returning HTML are counted, so a scanner requesting
random URLs produces 404s, not rows. The in-memory buffer is capped at 20,000 views; beyond that
views are dropped and tallied. More caps bound table growth against a client that sends
browser-looking requests in a loop: one visitor (host, IP, user agent) adds at most 30 rows per
10-second flush window (
maxViewsPerVisitorPerFlush); one client address (an IPv6 address by its /64), whatever user agents it rotates through, at most 300 (maxViewsPerIpPerFlush); and an instance inserts at most 500,000 rows a day (dailyRowBudget). Views over a cap are not stored but are tallied asdropped, which the dashboard andnotCountedshow, so a capped day reads as capped rather than silently low. Every stored string is length-capped, and every value the page renders is HTML-escaped. - The daily budget is not a blinding switch for one client. Once the budget is spent nothing
more is stored until midnight, so a single client that could spend it (500,000 requests, about
four minutes at 2,000 req/s) could hide everyone else's traffic for the rest of the day. One
client address may use at most 2% of the budget a day (
maxDailyRowsPerIp, tallied for up to 50,000 addresses), so after one source hits its share, other visitors' views are still stored. Many sources together can still spend it; when that happens,/ops/analyticsshows "Row budget reached at HH:MM, N views not stored", the JSON report carriesrowBudget, and a warning is logged once that day. - The "don't count" cookie.
POST /ops/analytics/ignoresets__brace_analytics_ignore=1(HttpOnly,SameSite=Lax,Path=/,Secureexcept on localhost). It carries no credential; it only marks the browser's visits as excluded. The endpoint is CSRF-exempt like the other ops POSTs: it requires theSameSite=Strictops cookie or a bearer token, and its only effect is a cookie on the caller's own browser. next=analyticson the login exchange is a fixed allowlist entry, not a URL, so it can't be used as an open redirect.
Brace scrubs error records at capture time, before they reach the database or
/ops/errors: BraceHandler redacts the request path, query string, headers,
exception message and stack trace at the point the exception is caught, and
ErrorStore.record redacts the stack trace again. Everything here is in
Redactor.
The same passes also run in the log and stats sinks themselves:
Log.request/Log.error redact the request path and the exception message
before the entry reaches stdout or the /ops/logs ring buffer, every Log
entry's fields are redacted by name, Stats redacts route keys, error messages
and stack traces before they are served on /ops/status, and analytics stores
redacted paths. A reset token in a URL path is therefore scrubbed on every
request, including successful ones, not only when an exception is thrown.
Two placeholders tell the passes apart: [REDACTED] means the value was
replaced because of its name (or it was URL user info), [redacted]
because of its shape.
Redaction fails closed. No public Redactor method throws. If one hits an
internal error it returns the marker [redaction failed] in place of the text
it was given, never the text itself: redactMessage, redactQuery,
redactUrl and redactPath return the marker alone, redactStackTrace puts
it in place of the line concerned (frames are kept), redactHeaders in place
of the header value concerned, redact(Map) in place of every value, and
isSensitive/isSensitiveField answer true. The redactor runs inside the 500
handler, so a throw there used to lose the error being recorded. If you see
[redaction failed] in an error record or a log line, that is a bug in the
redactor worth reporting; nothing leaked. The 500 handler itself also keeps
going when recording fails: each of the stats, the http.error log line and
the error store is written on its own, and the client always gets the
framework's 500.
There are two name rules, because a short word such as code is a credential
in a query string but ordinary data in a log field.
| Rule | Applies to |
|---|---|
In transit (Redactor.isSensitive) |
query parameter names (percent-decoded first: %74oken= is token=), request header names, and name=value pairs found inside header values, URLs and path segments (;jsessionid=) |
Fields (Redactor.isSensitiveField) |
structured log fields (every Log entry, through Redactor.redact, nested maps and lists included), analytics route parameter names (/reset/{token} is stored as /reset/{token}), and name=value pairs inside exception messages |
Both rules match:
- A substring of the normalized name (lowercased,
-and_removed):authorization,cookie,password,passwd,pwd,secret,token,apikey,bearer,credential,privatekey,accesskey,sessionid,csrf,jwt,assertion,signature,authkey,nonce(Redactor.SENSITIVE). This deliberately over-redacts:token_countis redacted too. - An auth-paired
code. The name is split into segments on_ - . [ ]and other punctuation and at camelCase boundaries, ignoring a leadingX-. Acode(or pluralcodes) segment is sensitive next to one ofauth,authorization,authentication,oauth,verification,verify,verifier,reset,otp,totp,hotp,sms,mfa,2fa,tfa,pin,pass,password,invite,invitation,access,login,signin,confirm,confirmation,activation,activate,recovery,backup,security,magic,device,unlock,onetime,twofactor(Redactor.CODE_QUALIFIERS), and so is one of those words fused withcodeorcodes(passcode,authcode,otpcode,onetimecode,passcodes);backup_codesandrecovery_codesare sensitive likebackup_code. Two pairs of segments qualify acodeas well:one+time(one_time_code) andtwo,2,multiorsecond+factor(twoFactorCode).
The in-transit rule also matches a name that is exactly code (an OAuth
authorization code; X-Code too), a segment sig, otp, totp, pin,
sid, ticket or session (Redactor.TRANSIT_WORDS), and a name whose last
segment is auth, mfa, 2fa, tfa, verification or a second factor
(X-Auth, X-Upstream-Auth, X-MFA, email_verification, two_factor;
Redactor.TRANSIT_LAST_WORDS). Those last words name the value only when they
end the name: mfa_enabled, two_factor_enabled and verification_status
are kept. The field rule instead matches only a field named exactly otp or
totp.
| Name | In transit | Field |
|---|---|---|
token, api_key, X-Auth-Token, password, session_id, client_assertion |
redacted | redacted |
auth_code, verificationCode, reset_code, otp_code, pin_code, device_code, code_verifier, passcode, backup_codes, recovery_codes, onetimecode, one_time_code, twoFactorCode, mfa_code |
redacted | redacted |
code, X-Code |
redacted | kept (code:"card_declined", /countries/{code}) |
sig, pin, sid, ticket, session, user_session, account_sid, sms_otp, X-Auth, X-Upstream-Auth |
redacted | kept |
mfa, 2fa, two_factor, verification, email_verification |
redacted | kept (mfa:true, verification:"pending") |
otp, totp |
redacted | redacted |
zip_code, status_code, error_code, country_code, currency_code, postal_code, promo_code, code_challenge, user_code, zip_codes, status_codes |
kept | kept |
postcode, barcode, encode, codec, signal, design, sigma, pinned, sessions, sidebar, tickets, author, authority, auth_method, X-Auth-Request-User, state, mfa_enabled, two_factor_enabled, verification_status |
kept | kept |
state (the OAuth CSRF value) and promo_code are deliberately not
sensitive. A malformed percent-escape in a name is kept literally, never an
error.
Free text (an exception message, a header value, a path segment, a query
value) is scanned left to right by Redactor.redactText, in three passes at
once:
-
Embedded URLs. Every
scheme://…(any scheme:https,postgres,jdbc:postgresql,redis,amqp,smtp,s3…), every</path?query>(aLinkheader), and a/pathvalue aftername=(Refresh: 0; url=/reset?token=…,Forwarded: uri="/reset?token=…") goes throughredactUrl: anyuser:password@becomes[REDACTED]whatever its shape, the path throughredactPath, the query and fragment throughredactQuery; scheme, host and port are kept. A URL ends at whitespace, a quote,< > \ ^ { } |, and loses trailing. , ; : ! ? ) ]. A scheme is found inside a run too, whatever it is: at://the scan backs up over letters, digits and+ - .(GET /proxy/https://user:pw@host,1https://,backup_ldap://cn:pw@hostisldap://,jdbc:my_driver://isdriver://). A "scheme" that is itself secret-shaped (a token glued to://) is replaced.User info. An
@before the first/ ? #ends the user info, as in any URL parser. A password can also hold a character that would end the URL or the authority, so two more cases are masked:- A password with an unencoded
/,?,#or;(postgres://user:pa/ss@host,redis://:pa?ss@host): masked up to the last@of the URL, when the text before the first/ ? #holds a:and is not evidently a host. A list of two or morehost[:port](mongodb://h1:27017,h2:27017/db?authSource=a@b) is evidently hosts and keeps its path and query. So does one host with a dot,localhostor an IPv6 literal when the scheme ishttp,https,wsorwss(https://example.com:8443/users/@bob,http://localhost:3000/assets/logo@2x.png) or when the@is in the query (postgres://db.internal:5432/app?email=a@b.c); in any other scheme an@inside a path segment still ends the user info, becausepostgres://first.last:12345/678@db(a dotted user name, a numeric password with a/) looks exactly like a host, a port and a path. One dotlessname:digitscan be a host and port (db:5432) or a user and a numeric password cut at its/(user:12345/678@host): redaction wins the tie in every scheme, soredis://cache:6379/0?client=a@bis stored asredis://[REDACTED]@b. - A password with
^ { } | \a backtick,',<or>(jdbc:postgresql://app:p^ssw0rd@db/x): the URL does not end there when the authority so far holds:, no@and no/ ? #, is not evidently a host, and an@follows within 256 characters before any whitespace. One space is passed the same way when what follows the:cannot be a port and the next word holds the@(postgres://app:my pass@db). A double quote always ends the URL.
Parameters after the host (
jdbc:sqlserver://db:1433;user=sa;password=…, a;name=valuebefore any/ ? #): the whole rest of the URL gets thename=valuepass, so a password there may hold/,?,#or@. - A password with an unencoded
-
name=valuepairs. When the name before=is sensitive (the in-transit rule, or the field rule inside exception messages), the value becomes[REDACTED]: up to whitespace or one of& ; , " ' < > ( ) [ ] { } | \, so the next parameter is never swallowed; or, when the value opens with",',(,[,{or<, up to the matching closer (password={a;b}ispassword={[REDACTED]},backupCodes=[a1b2c-d3e4f, g5h6i-j7k8l]isbackupCodes=[[REDACTED]]). Brackets of one kind nest, a doubled}or'inside is an escaped one (SQL Server's{a}}b}, SQL's'it''s'), and with no closer the value runs to the end of the line. -
The run rule. Every other maximal run of
[A-Za-z0-9_\-+/.~$%]is tested wherever it sits (next to a quote, a<, a full stop):- A run holding
%is percent-decoded up to 3 rounds (%252Fis/); if any decoded round has something to redact by these same rules, the whole run becomes[redacted]. - A JWT (two dots, three base64url parts, the outer two at least 10
characters) or a two-part
payload.signaturetoken (one dot, at least 20 base64url characters each side, a digit and a letter: the ops bearer token's own shape) becomes[redacted]whole. - A Java qualified name (three or more identifier labels starting with a
common root such as
java,com,org,io:com.amazonaws.services.s3.model.AmazonS3Exception) and a hostname (three or more DNS labels ending in a common TLD such ascom,net,io,internal,local, or two labels ending ininternal,local,localhost,lanorcorp:db-primary-7f8c9d.internal) are kept whole. - A label with
/is a file path when every/-piece looks like part of one: no+anywhere; no piece under 16 characters mixes upper case, lower case and digits; and a piece of 16 or more characters without a digit is cased like words (lower case, upper case, Capitalized, or a camelCase name such asAdminDashboardController). Standard base64 uses/too, and this is what tells the two apart: the tail of AWS's example key,bPxRfiCYEXAMPLEKEY, is not cased like words, sowJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYis judged whole and redacted. A path whose pieces are all plain is kept (/var/lib/app/uploads/2024/11/05/invoice-48213-final-v2.pdf,db/migration/V3__create_users_table). A path with a secret-shaped piece loses that piece alone when the run starts like a path (/,./,../,~/; a drive letter'sC:is outside the run) or ends in a file extension, and its short pieces are words or simple camelCase:/tmp/brace-uploads/upload-8a7b6c5d4e3f2a1b.tmpis/tmp/brace-uploads/[redacted].tmp,Failed to load /assets/main-3f9a1c2b4d5e6f7a8b9c0d1e.cssisFailed to load /assets/[redacted].css. Without that evidence the whole label is replaced (exports/<token>/datais[redacted]). - Otherwise each label between
. ~ $ %is redacted when all of these hold: it is at least 16 characters of[A-Za-z0-9_\-+/]; it contains an ASCII digit and an ASCII letter; it is not a UUID (8-4-4-4-12hex); and it is not a name made of words (below). The separators are kept:T.is[redacted].,/dl/T.pdfis/dl/[redacted].pdf,SG.x.yisSG.[redacted].[redacted],T~xis[redacted]~x.
Names versus secrets. A label is a name, and kept, when it is made of words: it holds only
[A-Za-z0-9_-], it is split into parts on_and-and each part into words (a leading digit group, or letters cut at camelCase boundaries with an optional trailing digit group), and:- it has two or more words, at least one of three or more letters;
- every word of five or more letters reads like a word: each pair of
adjacent letters is scored by how usual it is (a 26 by 26 table ranked
over English and identifier text), and the score may not pass two thirds
of a point per pair, so one unusual pair is forgiven and a run of them is
not (
create,users,Handler; notZAXVVMA,htvmuprj); - a digit group has at most 6 digits on its own (
48213,000482), or 8 that read as a date (20241105), and at most 3 after letters (v2,V19), and at most one word has both letters and digits; - letters and digits are not interleaved: a digit followed directly by a
letter, other than at a camelCase boundary (
Http2Connection), is allowed once and only in a part shaped like2024q4; - at most one word is a one- or two-letter fragment inside a longer part;
- in a camelCase part every word has four or more letters (
Http,Line), except a first lower-case word (get,shipping) and one acronym of two to four capitals that starts the part or carries the digits (UTF8,XML); no word has five consonants in a row; - it is not three or more parts of (nearly) one length (the shape of a
grouped code,
abcd5-efgh6-ijkl7); and two parts of (nearly) one length, seven or more characters each, are a name only under a stricter word score, half a point per pair (shipping_address2is kept,PZEEBRLL_HGZUZTU3is not).
Also names: a JVM address,
0xand 16 hex digits of which the first four are zero (a lambda's$$Lambda/0x000001f0a1047000), and agit describesuffix after a tag part, with a count of at most 5 digits (2024.11.05-1423-g3f9a1c2,v1-1423-g3f9a1c2). SoV3__create_users_table,invoice-48213-final-v2,user_sessions_archive_2024q4,CONSTRAINT_INDEX_4,audit_log_entries_2024,PARTIALLY_REFUNDED_V2,ORD-2024-11-000482,shippingAddressLine2,Http2ConnectionHandlerImplandUTF8StreamJsonParserare kept, while a hex hash (8a7b6c5d4e3f2a1b, a 40-hex commit SHA), a random token, a two-group code (ZAXVVMA5-LAHQRWYU), a Stripe id (pi_3OaBcD2eFgHiJkLm), a word joined to a secret or to a long number (reset-8a7b6c5d4e3f2a1b9c0d,token_Ab3dE9fGh1JkLmN0pQrS,reset-code-48213977) and any other0xliteral of 16 or more characters are redacted.Measured. A seeded test (
RedactorTest.randomTokensOfEveryShapeAreRedacted) draws 100,000 random tokens of each of 41 shapes and fails when more than 1 in 10,000 of a shape the name rule judges keeps half or more of itself. On 300,000 tokens per shape: hex, base32, base36, Crockford and base64url tokens of 16 to 43 characters, ungrouped or in groups of 4 to 6, none kept; base62 of 16 characters 1 in 40,000, of 20 or more none; two groups of 8 or 9 (the worst shape) 1 in 20,000 for base32, 1 in 50,000 for base62, 1 in 100,000 for base36, none for hex. Standard base64 can also read as a path of short pieces (YGw/A0C3B/hJOQFgnBClnm): 22 characters 1 in 1,250, 27 characters 1 in 5,500, 40 characters 1 in 150,000, 43 or more none in 300,000. These base64 figures are the same as before paths and names were told apart. - A run holding
= is not part of a run (it separates a name from its value, and base64
padding is not secret). Recursion through URL-inside-URL values stops at 4
levels; deeper content becomes [redacted]. All of it is linear in the input:
the review's worst cases (64 KB and 1 MB of %, &, dots, %25, =, nested
URLs) are a test.
Where it runs:
| Where | How |
|---|---|
| Request path (error record, logs, stats, analytics) | redactPath: each /-segment gets the free-form pass with the in-transit rule. A segment is also tested percent-decoded (up to 3 rounds), and a ;name=value matrix parameter is redacted by name (;jsessionid=, ;token= become [REDACTED]) or by shape. A path whose segments are all under 16 characters and that has no = is returned at once |
| Exception message and stack trace | redactMessage / redactStackTrace: the free-form pass with the field rule for pairs. In a stack trace every message line (Caused by:, Suppressed:, at any indent, and multi-line messages) is redacted; frame lines are kept: ... N more, ... N common frames omitted, and at followed by a frame as the JVM prints it, [loader/][module[@version]/]pkg.Class.method(File.java:12) with (Native Method) or (Unknown Source) and an optional Logback ~[jar:version], after one or more tabs or spaces (so the frames of a Suppressed: exception and of the causes under it too). A line that merely starts with at is message text and is redacted: Jackson's at [Source: (String)"{…}"; line: 1, column: 3] quotes the document it failed on |
Query string (error record requestDetail, stats) |
redactQuery: a part whose percent-decoded name is sensitive (in-transit rule), or whose value, as sent or after up to 3 rounds of decoding, has anything the free-form pass would redact (a secret-shaped run, a URL with something to redact such as ?next=https%3A…%3Ftoken%3D…, a sensitive pair), becomes name=[REDACTED]; a bare ?<token> part becomes [REDACTED] |
URL-valued request headers (Referer, Origin, Location, Content-Location, X-Original-URL, X-Forwarded-Uri, X-Rewrite-URL, HX-Current-URL) |
redactUrl, as in pass 1. A value that is not a URL gets the free-form pass |
Other request headers, Forwarded and Via included |
redactValue: a value that is one URL or path with no whitespace goes through redactUrl (or becomes [redacted] whole if it is secret-shaped as a whole, since a standard-base64 secret can start with /); anything else gets the free-form pass with the in-transit rule. Forwarded: for=…;by=…;proto=…;host=… stays readable while its uri="…" is redacted; a JWT in X-Amzn-Oidc-Data or Sec-WebSocket-Protocol (base64url.bearer.authorization.k8s.io.<token>) is caught |
| Protocol-metadata headers | kept verbatim: Accept, Accept-Charset, Accept-Encoding, Accept-Language, Cache-Control, Connection, Content-Encoding, Content-Language, Content-Length, Content-Type, DNT, Expect, Host, HTTP2-Settings, the conditional headers (If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, If-Range), Keep-Alive, Pragma, Priority, Range, TE, Upgrade, Upgrade-Insecure-Requests, User-Agent, X-Requested-With; exactly four of the X-Forwarded-* family (X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto) plus X-Real-IP, CF-Connecting-IP, True-Client-IP, CF-IPCountry, CF-Visitor; request ids and trace context (X-Request-Id, X-Correlation-Id, Request-Id, traceparent, tracestate, Cf-Ray, X-Amzn-Trace-Id, X-Cloud-Trace-Context, B3); Sec-Fetch-*, Sec-Ch-*; the WebSocket key, version and extensions; htmx's request headers (Redactor.VERBATIM_HEADERS). Their values are never a user's credential, and the shape rule would misfire on an ETag, a multipart boundary or a request id. Any other X-Forwarded-* header gets the free-form pass |
| Log fields | by name only (field rule), recursing into nested maps and lists. Nesting deeper than 64 levels, or past 100,000 copied values (a map that contains itself, a shared child under many keys), becomes [nested too deep] |
The request headers are redacted by Redactor.redactHeaders, in that order:
a sensitive name (in-transit rule) first, then the URL, verbatim or free-form
rule.
What is intentionally kept visible:
| What | Why |
|---|---|
UUIDs (8-4-4-4-12 hex), anywhere |
Usually record identifiers, not bearer secrets; needed for debugging. A request id that is not a UUID is kept only in the request-id headers above |
| Purely numeric values and runs | Page IDs, order numbers, user IDs |
| Short labels (< 16 chars) | Route labels, action names, dotted versions (4.12.0-beta.3+build.20241105), file names whose labels are short (app.3f9a1c2b.js, Brace's own ?v=a1b2c3d4 fingerprint) |
| Java qualified names, hostnames ending in a common TLD | com.amazonaws.services.s3.model.AmazonS3Exception, my-loadbalancer-1234567890.us-west-2.elb.amazonaws.com, db-primary-7f8c9d.internal, a CloudFront Via |
| Names made of words | V3__create_users_table.sql (any Flyway file name, Brace's own included), invoice-48213-final-v2, CONSTRAINT_INDEX_4, shippingAddressLine2, Http2ConnectionHandlerImpl, 2024-black-friday-sale |
| File paths | /srv/app/uploads/2024/11/report-final.pdf, /var/app/releases/20241105, exports/2024/11/05/customer-orders-2024-11-05.csv; in a path that starts with /, ./, ../ or ~/ or ends in a file extension only a secret-shaped piece is replaced (/tmp/brace-uploads/[redacted].tmp) |
| Stack frame lines | at pkg.Class.method(File.java:12) and ... N more at any indent, the frames of Suppressed: exceptions included |
| Host lists and hosts with a dot | mongodb://h1:27017,h2:27017/db?authSource=a@b, postgres://db.internal:5432/app?email=a@b.c, https://example.com:8443/users/@bob: an @ beyond them is not user info (outside the web schemes, one inside a path segment still is) |
| Email addresses | PII, not a credential; @ is outside the run alphabet and each label is short |
Comma- or #-separated lists (#ff0000,#00ff00) |
Each item is short |
| Exception message text without high-entropy tokens | Needed to diagnose the error |
Known over-redaction. What the rules cannot tell from a secret, and so redact:
- A 16+ character label of letters, digits,
-,_,+or/with both a digit and a letter that is not a name made of words: a dash-joined hex listff0000-00ff00-0000ff, a 16+ character hex hash (a commit SHA in a message), a pod nameweb-7d9f8b6c5-x2k4q,db-primary-7f8c9doutside a hostname, a name with a one-letter camelCase word or two words holding digits (AmazonS3Exception,OAuth2AuthorizationCodeGrantFilter,utf8mb4_0900_ai_ci), three parts of one length (test-case-data-2024), a name with a 7 or 8 digit group that is not a date (test-user-12345678), and a name holding a word the letter-pair table scores as unusual (proxy,nginx,jsonb; about 1 use in 200 of the five-letter-or-longer words in Brace's own sources). These look exactly like a grouped recovery code or a token. - A dotless host with a port, in any scheme, when an
@follows in the path or query:http://api:8080/users/@bobandredis://cache:6379/0?client=a@bare stored ashttp://[REDACTED]@bobandredis://[REDACTED]@b, becauseuser:12345/678@hosthas the same shape. Outside the web schemes the same holds for a host with a dot and a port when the@is inside a path segment:s3://bucket.example.com:443/exports/a@b.csvis stored ass3://[REDACTED]@b.csv. - A relative path with no file extension and a secret-shaped piece
(
exports/<token>/data) is replaced whole, and so is a path where a secret piece sits next to a directory that is not cased like words (/opt/iOS/…). - A sensitive value that opens with a bracket or a quote and never closes it takes the rest of its line.
- A content hash of 16 or more characters in a file name:
/assets/main-3f9a1c2b4d5e6f7a8b9c0d1e.cssis stored as/assets/[redacted].css, and so is a bundler chunk such asProductDetail-a1B2c3D4.js(the label is 22 characters). Chosen deliberately: such a name cannot be told from a download token in/dl/<token>.pdf. The cost is cosmetic, in error records and logs only. - A two-label host whose last label is a public TLD
(
abcdef1234567890xyz.com). - A
/-joined value with a long or mixed-case-and-digit piece (/files/Ab3dE9fG/rawas a whole header value), since a standard-base64 secret can contain/. - In transit, names that only look sensitive:
ticket_id,session_count,pin=1,otp_enabled,sig_alg,account_sid(an identifier), and any name ending inauth,mfa,2faorverification(?verification=pending). In exception messages,token=…orpassword=…text that is not a credential.
Known limits. What the rules do not redact. Treat the error store and the logs as holding secrets of these kinds, and keep them out of exception messages and URLs where you can:
- A secret under a sensitive name that is not written
name=value. The name pass reads=only. JSON ({"password":"hunter2"}), a colon (password: hunter2), spaces around the sign (password = hunter2) and prose (the password hunter2 was rejected) are not matched by name. A value there is still caught when its shape is secret-like (16 or more characters with a digit and a letter, a JWT), so a long API key in a JSON excerpt goes and a short password stays. - A short secret under a name the rules do not know. Under 16 characters
nothing is redacted by shape: a 6-digit code in
?c=123456, a short password in a message. - A secret made of words.
CorrectHorseBattery1,monkey_dragon_letmein_2024and any passphrase of dictionary words with a short number read as names, by design of the name rule above, and are kept unless a sensitive name stands before them. - A secret of letters only or digits only, of any length: the shape rule needs both a digit and a letter.
- A space inside an unquoted value.
password=abc def123losesabconly. The one exception is the single space inside URL user info described above. - Standard base64 that reads as a path of short pieces. A base64 value
whose
/-pieces are all under 16 characters and none of which mixes upper case, lower case and digits is kept (abcdefghijklm/NOPQRSTUVWXYZ/0123456789012): the measured rates are above. Likewise a value cut by/or.into pieces that are each under 16 characters is never redacted by shape (a69a83f4/07210da8/180c9c1b,wmb5q8pnsd23k9i.ok5g34xcrge1ztx), whatever it is. - A request path is judged segment by segment (
redactPath), so a base64 value with/inside a URL path is several short segments. - User info that looks like a host. A dot in the user name and a numeric
password cut by an unencoded
/,?or#read as a host, a port and a path or query.https://first.last:12345/x@hostis kept (in a web scheme the path wins, forlogo@2x.png), and so ispostgres://first.last:12345?x@hostin any scheme (the query wins). Percent-encode such a password, as the URL syntax requires, and it is masked. - A line shaped exactly like a stack frame inside a multi-line exception message is taken for one and kept.
If your application routes embed raw bearer tokens or reset secrets in path
positions, consider moving them to opaque database-lookup keys so the route
keeps its meaning after redaction. Exclude such routes from analytics with
.analytics(false) when the parameter name does not say it is secret
(/invite/{code}).
Error records carry client-controlled text, so ErrorStore makes sure no single record can
block the others:
-
ErrorStore.recordreplaces NUL characters with U+FFFD. A request such as?page=1%00puts a NUL in aNumberFormatExceptionmessage, and Postgres text cannot hold one. Replacing it instead of deleting it keeps already-redacted tokens from being joined into one secret-shaped token. The error type and route are clipped to their 255-character columns; the route starts with the client-chosen HTTP method. -
Each upsert in a flush runs under its own savepoint. A row the database rejects is rolled back alone, and the rest of the batch commits.
-
A row rejected for its data (SQLState class
22data exception,23integrity constraint,54program limit) is retried once, in the same flush, with its payload stripped: a new error kind is inserted with a fixed placeholder message ([details not stored: the database rejected this error record], no request-derived text) and an empty stack trace, request detail, queries and headers; an error kind that already has a row only gets its count and last-seen time updated, so its stored details are never replaced by the placeholder. The count and the regression notification survive. Any other row rejection (a lock timeout55P03, a statement timeout, an error without a SQLState) is not retried stripped: the full record is retried on the next flush. -
A rejected entry is retried on later flushes, and dropped after 5 rejected flushes.
-
Not blamed on any entry, so the whole batch is kept, uncounted, and retried, bounded by the 1,000-kind pending buffer:
- a connection-level failure (database down, pool exhausted, failure to open the session or begin the transaction);
- a server-wide SQLState when no row of that flush could be written, whether or not the
connection still passes
isValid:25006(read-only transaction, as during a failover), class53(disk full, out of memory, too many connections),57P01to57P05(shutdown), class58(system error), class08(connection). When another row of the same flush was written, the server is taking writes, so the state counts against that row alone (dropped after 5 such flushes) and the other rows commit; - another connection-classed SQLState (
40, other57, other25) when the connection also failsisValid.
That retention is capped at 60 consecutive flushes per entry (about two minutes). After that each further failed flush counts like a row rejection, so an outage longer than about two minutes drops the entries it holds after 5 more flushes, reported by the rate-limited warning, instead of keeping the pending buffer full for good. Every other row error is a row rejection like any other, even when every row of the batch gets the same one (a lock timeout on every row), and so is a connection-classed error on a live connection (for example
57014, a statement timeout on one huge row): a single poisoned row is still isolated and dropped after 5, and kinds that always fail that way cannot fill the buffer and lock out a new kind. -
The 1,000-kind cap covers everything the store holds: pending kinds plus the batch a flush is writing. While a flush waits on an unreachable database, new kinds past the cap are dropped (and counted in the "error storm" warning); the kinds buffered first, with their counts, are kept.
-
In error kinds and in the
/ops/statusroute stats, a request method outside GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE and CONNECT appears asOTHER, so a client cannot create kinds or stats keys with made-up methods. The request log line and an error's request detail keep the method as sent. -
Failures are logged at most once a minute, naming the exception class, SQLState and the error type of any dropped entry. Request-derived content (messages, paths, headers) is never logged. The warning distinguishes kinds dropped "after 5 rejected flushes" from kinds "the database could not take through 65 failed flushes". A
RegressionListenerthat throws loses only its own notification, and anErrorduring a flush keeps the batch and the flusher thread.
Before the 2026-11 security review (M5), one such request failed every later flush on
Postgres, so nothing reached ops_errors and regression alerts stopped until restart.
A new error kind's message can contain text a web user chose. WebhookNotifier (Slack and
Mattermost incoming webhooks) therefore puts the type, route and message each in an inline code
span, which both render literally: Mattermost markdown links, images (a tracking pixel) and
emphasis are inert. Inside the span, a backtick (which would close it) becomes ˋ, < > &
(Slack control sequences such as <!channel>) become ‹ › &, @ becomes the full-width
@ so no @channel mention fires, and line breaks and control characters become spaces. The
message is cut to 500 characters first. Backslash escaping was not used because Slack does not
honour it. MailerNotifier sends plain text.
Mailer over smtp://user:pass@host:587 requires STARTTLS
(mail.smtp.starttls.required=true). If the relay's EHLO does not offer it, the send fails
instead of continuing in cleartext, so a network attacker cannot strip the offer and read the
SMTP password and mail bodies (password-reset links). smtps:// is implicit TLS. A trusted
local relay that cannot do TLS (a sidecar on localhost) opts out explicitly with
smtp+plain://localhost:25, which uses STARTTLS when offered but never requires it. Credentials
on an smtp+plain:// URL are allowed but logged as a warning once, when the Mailer is
constructed (the host is named; the user and password never are), because without TLS the AUTH
exchange is cleartext. The scheme is compared case-insensitively (SMTPS:// is implicit TLS).
Dev mode (no SMTP URL) only captures mail and is unaffected.
The SMTP URL is parsed once, when the Mailer is constructed. A malformed one (a password with
an unencoded ^, space, | or #) throws IllegalArgumentException there, naming the
smtp.url setting and asking for percent-encoding, but never including the URL or chaining the
parser's exception: its message is the whole URL, password included, and used to reach the
error store's stack trace as the cause of every failed send.
Mailer.to(...) takes exactly one address and parses it strictly, so a recipient taken from a form
cannot add recipients ("a@b.c, victim@x.y" throws). The same holds for cc(...), the
per-message from(...), and Mailer.from(...)/Mailer.replyTo(...) (checked when configured).
Strict parsing yields exactly one address or throws; on top of that, group syntax
(g: a@b.c, victim@x.y;, several mailboxes as one address), route addresses
(<@relay:a@b.c>) and control characters are refused. A comma inside a quoted display name
("Doe, J" <a@b.c>) is one mailbox and is accepted. @Email likewise rejects , ; < >,
( ) ", whitespace and control characters, and accepts only a value that parses as one bare
address equal to itself: an RFC 822 comment (evil@attacker.tld(ceo@corp.example)) would
otherwise be sent as the display name. MailerNotifier accepts several recipients, validates each at
construction and sends each its own message.
- Minimum: 32 bytes of random data
- Generate with:
openssl rand -base64 32oruuid4().toString() - Never use: "secret", "changeme", "test123", predictable values
Store secrets in environment variables, not in code:
var secret = System.getenv("SESSION_SECRET");
if (secret == null) {
throw new IllegalStateException("SESSION_SECRET not set");
}
app.sessions(secret);Use Config for environment-aware configuration:
var config = Config.load();
app.sessions(config.require("session.secret"));
app.ops(config.get("ops.keys.path", "authorized-keys"));When rotating secrets:
- Sessions: Users will be logged out on rotation
- Ops keys: Add new keys before removing old ones
- Database credentials: Use connection pooling with graceful reload