Security model#
Zubra draws one trust boundary: the .zb source is code you trust; the values flowing into it are data you don't. Props, attribute values, slot content supplied at build time, and values your script computes at runtime are all treated as untrusted. The rules below are enforced identically by the HTML output (at build time) and by the runtime (in the browser), so a component that is safe when server-rendered is safe when it updates.
The playground treats shared source and markup as untrusted: previews run in sandboxed, opaque-origin frames. Sync data is scoped to the exact component and page pair, so editing either starts a separate store; previews of the same pair can still share updates.
What the compiler and runtime guarantee#
Text is text. Every {expr} in text is escaped in the HTML output and written with textContent (or a text node's data) at runtime, never parsed as HTML. There is no "raw HTML" binding.
Attribute values are values. Dynamic attribute values are escaped in the HTML output and written with setAttribute at runtime. An object or array can't be written to an attribute; it's reported and the attribute is removed. (Objects reach custom elements as properties instead.)
A streamed error stays on the server. When a prop given as a promise rejects, the browser gets "Internal error" in production and the error's message only in development; the error goes to createZubra({ onError }), or to the log with its stack. A database's error, which can name hosts, users and queries, never reaches the page. Node defaults to production unless NODE_ENV=development or production: false is set; @zubra/server/edge is production unless told production: false.
Production is the default on servers. @zubra/server and @zubra/actions are in development mode only with NODE_ENV=development or production: false; anything else, an unset NODE_ENV included, is production. So a deployment that forgets NODE_ENV still answers a failed request with "Something went wrong" (not the error's message, stack and absolute source paths) and serves the runtime's production build, not the DevTools one. Development says so at start (@zubra/server: development mode (NODE_ENV=development)).
Sync reads and writes are closed by default. createSyncServer() without authorize sends pages nothing from the log and refuses every write from them: a collection is readable only when the app names it (authorize: allowReads(['menu'])) or gives an authorize that decides, and writable only through authorize (allowAnyone opens both). A Durable Object without an authorize() and the zubra-sync binary without --read, --read-all or --open are the same. A field named key, $clocks, prototype, or a name every object already has (__proto__, constructor, toString, …) is refused, on a push and when a log that already holds one is read. A live stream is written only as fast as its page reads it: the log is read a page at a time as the page takes the last, and a stream more than 64 events behind is closed (its page reconnects from its cursor), so a page that opens one and reads nothing can't make the server hold the log for it. See Sync.
Server markup is adopted only when it is the template. Hydration walks elements and markers, not text, so a visitor's text can't forge a <?zb ?>. A comment or processing instruction in a slot can: <!--]--> or <?zb ]?> used to end the slot early and the component's listener bound to the element that followed. The live tree has to match the template at every element, static text included. Whitespace left where a marker was stripped does not count as different text; a different word does. A child component is its own template, so the walk doesn't enter one. A URL attribute, an event-handler attribute (onmouseover), srcdoc or ping that the template doesn't have and no part binds is removed. Any other attribute stays, including an id the page wrote on a slotted child that shares the template's shape. Anything else renders fresh.
URLs are checked. For URL attributes (href, src, action, formaction, poster, cite, background, codebase, data, longdesc, manifest, profile, usemap, xlink:href), the final value must be relative or use http:, https:, mailto: or tel:. In the HTML output the check decodes HTML character references first, so javascript: doesn't get through (at runtime, setAttribute never decodes them). Protocol-relative URLs (//host) and values with control characters are rejected too. Literal URLs are checked at build time everywhere, and an unsafe one is a compile error: the author wrote it. Computed URLs are checked on their final value, and an unsafe one leaves the attribute off, in the HTML output and on every update at runtime. Both say so: the browser in the console, and @zubra/server through createZubra({ warn }) (console.warn by default), with the attribute and the start of the value (the compiler's request response lists them as omitted). Values often come from a page's users, so one of them must not be able to fail the whole render; it gets the same outcome the browser gives it. srcset and imagesrcset are checked candidate by candidate under the same rule: a literal one at build time, a computed one on its final value, where one unsafe candidate leaves the whole attribute off. An empty computed srcset leaves the attribute off. A spread is checked the same way, and what it may never set (a handler as text, innerHTML and its kin, srcdoc, ping, an animation's values and target, a <meta>'s http-equiv) is left out with the same warning, on the server and in the browser, since the object is often a visitor's data. <base href> is the template's text only: interpolating into it is a compile error, because the base decides where every relative URL on the page goes, the runtime's and the components' own scripts included, and a visitor's https: URL there passes any URL check and runs their script. A spread can't go on <base> or <link> at all (a compile error), since their attributes decide what the page loads: { rel: 'stylesheet', href } is a visitor's CSS. Any interpolation into srcdoc is a compile error, because a nested document needs its own rules; so is one into ping, since a click posts to every URL it lists with the visitor's cookies, and into a <meta http-equiv>'s content, since a refresh redirects anywhere.
A spread's style must be an object; nested values and values that aren't a single safe CSS value are left out with a warning. Host attributes passed to renderToString (an Astro page's attributes on the component, and any other caller) are checked the same way: a name that isn't an attribute name, a string event handler, innerHTML and its kin, an object, and an unsafe URL are left off the HTML.
Boolean attributes take booleans. disabled={x} requires a boolean; a quoted interpolation into a boolean attribute is a compile error, so "false" can't silently mean true.
No string event handlers. onclick="…" is a compile error. onclick={handler} (or onclick={() => …}) binds a function written in the component, read when the event fires; it's left out of the HTML output. (Server-rendered slot content passed to the HTML output as HTML is the server's own markup and is kept as written.)
No inline styles or scripts in templates. style attributes, <style> and <script> elements inside a template are compile errors. The component's own <script> and <style> blocks, before the host tag, are the only code and CSS in a component. The <style> is static: no expressions, so values can't inject CSS. style:property={…} sets one CSS property. A value that isn't a single safe CSS value (it contains ;, braces, <, a backslash, url(), image(), image-set(), expression() or @import) is left off the element, so a visitor's string can't add a declaration or load an image: in the HTML output with a warning (createZubra({ warn }), and the compiler's response lists it as omitted), and at runtime. A literal one, which the author wrote, is a compile error. A visitor's value used to fail the whole server render instead, so one profile's colour could take down every page that showed it.
Attributes are parsed, never evaluated. A prop set from an attribute is parsed by its default's type: a number, a boolean, or JSON.parse for arrays and objects. Invalid JSON keeps the default and logs a warning. The HTML output writes every attribute in double quotes. A " or < in a literal piece of the value (the quotes around {name} in title='"{name}"', or title='she said "hello"') is escaped, so the value stays one attribute. An & already written in the source is left as written.
A spread can't set a meta refresh's target. http-equiv was already refused from a spread. So is content when the meta has http-equiv, or when the spread itself names http-equiv. A visitor's object can't turn the author's <meta http-equiv="refresh"> into a redirect, or replace a Content-Security-Policy meta's content.
Build-time expressions can't run code. The server evaluates only a deterministic subset: literals, operators, member access, template literals, arrow functions from the script, pure string, array, number, Math and Object built-ins, URI encoding, and regular expression literals. Regular expressions run on an ECMAScript engine with no access to anything but the string, and a pattern that could take exponential time (a repeat inside a repeat, | inside a repeat, a backreference) is never run on the server; the text a pattern searches is capped by how many repeats it has, so compiling a component can't be made to hang. It never evaluates Date, Intl, Math.random, window or document, assignment or new. The compiler interprets that subset itself, so compiling a component never runs its expressions as JavaScript. Expressions outside the subset are component code, like the <script>: they run only in the browser, in the JavaScript output, and their values reach the DOM through the same escaping and URL checks.
Redirects stay on the site, and never run script. @zubra/router's redirect(to) answers with a path on this site: a location starting // or /\ is written with one slash, and the result is read as a browser reads it and must stay on the request's origin. A location on this site whose path begins // (https://this.site//evil.example, .//evil.example, ..//evil.example) is written with one slash too, since a Location of //evil.example is another site. Any other origin is refused (a 500, through onError) unless the call says { external: true }, and a scheme other than http: or https: is refused even then. A location holding a control character (any C0 character, tab, LF and CR included, or DEL) is refused outright, because browsers drop tab and newlines from a URL: /\t/evil.example would arrive as //evil.example. So redirect(url.searchParams.get('next')) can't send a visitor off the site. @zubra/actions passes a returned redirect to the enhanced-form script (as zb-location) only when its location is http: or https:, and the script navigates to nothing else, ignoring it with a console warning; any other location goes out as the plain redirect, which neither fetch nor a browser follows. Unlike the router, an action's Response is yours: actions don't keep it on your site, so check a visitor's next before you redirect to it.
What is your responsibility#
- The script is your code. It runs with the page's privileges, as any module does. Treat a
.zbfile like a.jsfile in code review and dependency choices. - Slot content is the caller's markup. Content passed into a component's slots (children in HTML, a framework's children,
--slotsfragments at build time) is the caller's own DOM. Zubra moves it into place and doesn't sanitize it.--slotsfragments are parsed and validated by the compiler like templates. With--slots-htmlthey are the server's own HTML instead, and are kept as written. innerHTMLon a host behaves as on any element. Settingelement.innerHTMLon a Zubra element routes the parsed nodes into its slots, with exactly the platform's semantics for parsing that string. Don't pass it untrusted HTML, as with any element.- Context is visible to descendants.
provideanswers any element inside the provider that asks for that context key, including other libraries' elements, as the Context Protocol intends. Don't use context to pass secrets to specific elements. - Third-party custom elements that a template uses receive the values you bind (as properties once defined). What they do with them is up to them.
Reporting a vulnerability#
Please report security issues privately, through the repository's GitHub security advisories ("Report a vulnerability"), rather than in a public issue.
Development builds. @zubra/runtime's default export condition is its source, with the development warnings and the DevTools hook; the production condition (which bundlers use for a production build) leaves both out. The hook is readable only by scripts on the same page, which can reach the components through the DOM anyway, so it gives a page's own scripts nothing new. A page loading the runtime from a CDN should still load dist/production/ (or dist/bundled/).