Docs

Security

What Proa hardens by default, the CVE classes its design answers, and what stays your job.

Proa's security work splits three ways: what the template engine does automatically, what the framework hardens by default, and what remains application logic.

Knowing which bucket a concern falls into is most of the job.

What Proa does automatically

Three layers run without configuration: the macro refuses to compile some markup, the escaper encodes per context at render time, and the RSJS client runtime repeats the same guards in the browser.

Compile time

html! and html_sync! walk the template AST during macro expansion and run an OWASP-derived validation pass. Errors fail the build. Warnings compile but surface at the call site with the offending expression quoted back.

The static URL error looks like this:

html_sync! {
    <a href="javascript:alert(1)">"Click me"</a>
}
// error: dangerous URL scheme in `href` attribute. use a safe scheme
// (https:, /, #) or pass data via data-* attributes
// (OWASP XSS Prevention Cheat Sheet, Rule #7)

Two details make that check hold up against real bypass techniques rather than only the obvious spelling.

The attribute set is wide. Blocking href, src, action, and formaction is the common choice and it is not enough. Proa checks href, src, action, formaction, poster, ping, cite, data, background, longdesc, manifest, and both spellings of xlink:href. Each one is a real sink: poster fetches javascript: on older engines, ping is an exfiltration beacon, data on <object> executes, manifest was the AppCache vector. srcset is deliberately excluded, because its comma-separated url descriptor, ... grammar is not a single URL and a whole-string scheme check would be wrong there.

The scheme comparison is normalized the way a browser normalizes it. Two decoding passes happen before a URL reaches the parser, and a naive prefix match misses both:

• The WHATWG URL spec directs browsers to strip ASCII tab, LF, and CR from URL input. So java	script: and \njavascript: navigate fine. Proa skips ASCII whitespace and NUL throughout the scheme prefix, not just at the leading edge.
• The HTML5 parser decodes numeric character references inside attribute values before URL parsing. So javascript:alert(1) and the zero-padded javascript:alert(1) both work in a browser. Proa runs one pass of numeric-entity decoding with no digit cap, and treats a non-ASCII decoded code point as a non-match, since it cannot spell an ASCII scheme.

The blocked set is javascript:, vbscript:, and the executable data: types: text/html, application/xhtml+xml, application/xml, and image/svg+xml. Raster image, audio, video, and font data URLs stay allowed, because they have legitimate inline uses. SVG is blocked even when a particular payload looks inert, because it is an executable XML container.

Render time

Every dynamic value is escaped for its context before it reaches the output buffer:

let user_input = "<script>alert('xss')</script>";

html_sync! {
    <p>{user_input}</p>
}
// <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>

Attribute values are always double-quoted. There is no code path that emits an unquoted attribute.

Dynamic URL attributes get the same scheme check as static ones. A compile-time error cannot see href={user_supplied}, so the macro routes URL-bearing attributes through a runtime guard using the identical normalization. In debug builds a dangerous value trips a debug_assert!, so the mistake fails your test suite. In release builds the attribute renders with an empty value rather than the dangerous URL.

<script> and <style> content gets tokenizer masking. HTML escaping alone does not keep a value inside a raw-text element, because the tokenizer leaves raw-text state on byte sequences that escaping does not touch. Proa masks three of them with a single backslash, which is a no-op for the decoded JavaScript string value:

--> needs no mask of its own: every bare > is already escaped to >, so the sequence cannot appear in the output, and reaching the --> transition requires an unmasked <!-- first.

This is defense in depth, not permission. The compile-time warning still fires. The masking exists so a value that slips through a suppressed warning cannot escape the element.

Island hydration payloads are masked too. RSJS and React islands serialize props into <script type="application/json">. That content is raw text and textContent does not decode entities, so HTML-escaping it would corrupt the JSON. Instead </ becomes <\/ (a valid JSON escape for /) so the HTML parser cannot match a closing tag inside the payload, and U+2028 / U+2029 become their six-character escapes, since before ES2019 those acted as line terminators inside inline scripts and allowed breakout from a JSON string literal.

In the browser

RSJS repeats the server-side guards on the client, because a client-updated attribute is the same sink as a server-rendered one.

• The #[rsjs(...)] analyzer rejects dynamic bindings to any on* attribute, plus srcset, ping, srcdoc, and style. That is a compile error, not a warning.
• Dynamic URL attributes are classified and lowered to a sanitized binding.
• The runtime refuses to install any attribute matching /^on/i through setAttribute, and warns in dev mode. Reaching that branch means codegen regressed, so it fails closed.
• The runtime carries its own port of the URL scheme check, including the entity-decoding and control-character normalization, and blanks a dangerous value instead of setting it.

Good to know: RSJS enforces a fourth boundary. A value that never reaches a client root never ships to the browser, so secrets held in server-only components stay on the server by construction. See Server-rendered content.

CVE precedents this design answers

These are the published vulnerabilities the escaping and validation layers were reviewed against. Each one is cited in the source next to the code that answers it, so the reasoning survives refactors.

The data:text/html block is worth calling out separately. An allowlist that stops at javascript: and vbscript: leaves data:text/html,<script>...</script> as a working navigation payload, so the executable data: MIME types are blocked by the same code path.

Dependency advisories

Proa's own code is one half of the surface. The other half is the dependency tree, audited against the RustSec advisory database.

cargo audit --deny warnings
cargo deny check advisories bans sources licenses

.cargo/audit.toml and deny.toml hold the accepted-advisory list. Every entry is informational (unmaintained or unsound) with no fixed release available, and every one enters through an example app, developer tooling, a build-time processor, or a dev-dependency. None reach shipped library code on a request path.

The policy is that a false positive or accepted risk gets an entry in both files with a justification, and severity is never loosened globally. Revisit an entry when its parent dependency updates.

What the framework hardens

FrameworkBuilder::build() applies the same outer hardening to pages and endpoints:

Frame-policy overrides, HSTS, and Content Security Policy are opt-in, because each deployment needs its own. See Headers and CSP.

Cross-origin protection follows the pattern Go 1.25 ships as net/http's CrossOriginProtection. Rather than synchronizer tokens, it reads the Sec-Fetch-Site metadata header that every evergreen browser sends, with an Origin-versus-Host fallback for older clients. Safe methods always pass. A request carrying neither header passes, because it did not come from a browser and CSRF does not apply to it.

That is not a CSRF-token service. It rejects the shape of the request, not a forged token. Cross-origin and CSRF explains the difference and what you still need to add.

What stays yours

Proa gives you the attribute support these need, nonce, integrity, http-equiv, sandbox, allow, but the policy is yours:

• CSRF tokens and sessions. Configure issuance and validation in Axum middleware. Proa ships no session or cookie primitive.
• Input validation. Do it before data reaches a template, not after.
• Sanitizing user-authored HTML. Use an allowlist sanitizer such as ammonia before UnsafeRaw. Inside SVG or MathML, use a namespace-aware one.
• Cookie attributes. HttpOnly, SameSite, and Secure are server configuration.
• Redirect targets. There is no safe-redirect helper. Validate a user-supplied next= parameter against an allowlist yourself.
• URL encoding query parameters. Application logic.
• Rate limiting. Server middleware.

Two things no policy can rescue: inline event-handler attributes (onclick="…") never execute under a nonce policy, and a raw <script> tag you write by hand needs an explicit nonce read from cx.csp_nonce().

For untrusted data that genuinely has to reach client JavaScript, the supported pattern is <script type="application/json"> plus JSON.parse, not interpolation into a JS string literal. The macro escapers mask tokenizer breakouts, but they do not JSON-encode JavaScript string literals.

Reporting a vulnerability

Report privately through the Security tab of the repository on GitHub, using Report a vulnerability. That opens a private advisory visible only to you and the maintainers. Do not open a public issue with exploit details. See SECURITY.md for the supported surface and disclosure process.

Next steps

• Escaping and raw HTML
  • How Proa encodes dynamic values, and the two ways to opt out.
• Headers and CSP
  • Set frame policy, HSTS, and a nonce-based Content Security Policy.
• Cross-origin and CSRF
  • Reject forged cross-origin writes, and add the CSRF defense Proa does not.
• Server-rendered content
  • Keep ordinary Rust values and renderables outside an RSJS client graph.
• Environment variables
  • Configure a deployed Proa app without rebuilding the binary.