BizzPocket

Limits and security

On this page

A theme runs on every store that installs it and is seen by every shopper, so the platform does not trust it with more than it needs. This page explains the security model in plain terms, and the limits you will meet while building: what is cleaned for you, what you must check yourself, what data a theme can reach, how caching and cookies work, the content security policy, and the timeouts and caps.

The full list of numbers is in the limits reference.

The model in one paragraph: a theme renders data, it does not hold secrets or power. Seller input is cleaned before your render sees it. Data comes only through a fixed set of read-only storefront operations, scoped to the store being shown. Pages are the same for every shopper, so they can be cached. Only scripts the storefront itself wrote may run, and shopper sessions live in cookies a theme cannot read.


Rich text is sanitised

An f.richText() value is HTML written by a seller. Before your render sees it, the SDK rebuilds it from an allowlist, so you can put it in the page with dangerouslySetInnerHTML:

tsx
<div className="rt" dangerouslySetInnerHTML={{ __html: p.body }} />

What the sanitiser keeps:

Kept How
p, br, strong, em, b, i, u, s, span, small, sup, sub, code, pre, hr, blockquote as bare tags, with no attributes
h2 to h6 bare. There is no h1: the page has one already.
ul, ol, li bare
table, caption, thead, tbody, tfoot, tr bare
th, td with colspan / rowspan only, as whole numbers from 1 to 1000
a with href only when it is a safe URL, and target="_blank", which always gets rel="noopener noreferrer"

What it removes:

  • every attribute not listed above: style, class, id, onclick and every other event handler;
  • script, style, iframe, object, template, noscript and textarea, with everything inside them;
  • every other tag (div, img, h1, form...). The tag goes, its text stays;
  • comments, <![CDATA[...]]> and doctype-like tags;
  • nesting deeper than 256 open tags (the tags go, the text stays).

Text is escaped, and every open tag is closed at the end. A value longer than 200,000 characters (or the field's maxLength) is replaced by the field's default as a whole, never cut in the middle of a tag.

Warning. Only fields are cleaned. HTML that comes from data is not: a product's descriptionHtml, a page body from gql(). Run it through sanitizeRichText() from @bizzpocket/theme before you inject it: dangerouslySetInnerHTML={{ __html: sanitizeRichText(item.descriptionHtml) }}. It applies the same allowlist, so pictures and divs in that HTML are unwrapped.

Style the result through your own wrapper class (.rt p, .rt a), since the tags carry none.


Safe URLs

A link or picture URL can carry an attack (javascript:alert(1)) or send the shopper to another site (//evil.example). The SDK has two rules:

Rule Allows Used for
isSafeUrl(url) a path that starts with one / (/shop), a #anchor, and https:, mailto: and tel: URLs links (href)
isSafeMediaUrl(url) a path that starts with one /, and https: URLs pictures and videos (src)

Both refuse //host and /\host (browsers read them as another site), plain http:, data:, javascript:, and any URL with a control character in it (browsers strip tabs and newlines, so /\t/evil.example would become //evil.example).

Where they are applied for you:

  • f.link() values are checked with isSafeUrl, and f.image() / f.video() values with isSafeMediaUrl. An unsafe value becomes the field's default.
  • <Link href> drops an unsafe href (the text stays, the link goes).
  • <Image src> renders nothing for an unsafe src.
  • Links inside rich text are checked with isSafeUrl.

Where you check them yourself: URLs from data, such as a category's href, a social link or a menu item. Use toSafeUrl(value), which returns the trimmed URL or null, before you put it in a plain <a> or <img>. data.md shows the helpers.


Island props

An island's props travel from the server to the browser inside the page's HTML, as JSON in the island's data-props attribute. That has three consequences.

  1. Props are public. Anyone can read them with "View source". Pass only what the shopper may see. Never pass a token, a key, a cost price or another shopper's data.
  2. Props must be JSON. A prop may be a string, a number, a boolean, null, an array or a plain object. A function, a class instance, a Date, a Map or a JSX element is not data: the build stops with NON_SERIALIZABLE_ISLAND_PROP when it can see one. Anything it cannot see is dropped at render time (functions, symbols, bigints and React elements), and undefined disappears. Turn a Date into a string yourself.
  3. Props make the page heavier. Every byte is in the HTML of every page that shows the block. Pass the fields the island uses, not whole product objects.

Islands also get no JSX children, see no React context from the page, and can import neither @bizzpocket/theme-sdk nor zod (CLIENT_IMPORT_FORBIDDEN). The rules are in interactivity.md. The browser loads an island's code only from a path on the storefront's own address, the one the server wrote.


What data a theme can reach

A theme never talks to a database or an admin API. It reads data through storefront operations, and which ones depends on where the code runs.

Where How Operations
data() the data helpers products, product, related, categories, menu, store, home, search, and gql(document)
load() ctx.query(op, vars) the 13 public operations below, plus 5 shopper ones: customerMe, customerOrders, customerOrderDetail, customerSavedAddresses, customerWishlist
an island useQuery(op, vars) the 13 public operations below only

The public operations (BROWSER_QUERY_OPS in @bizzpocket/theme/client): productGridProducts, productSearch, productDetail, productSuggestions, productFrames, categoryTree, categoryTreeWithFeatured, categoryFilters, navigationMenu, storeProfile, storeHome, storePromotions and gemCertificate.

Rules that hold everywhere:

  • Read only. Every operation is a query. A theme changes nothing on the server: cart and account changes go through SIR events, which the storefront host carries out.
  • One store. The store is the one being shown. A storeSlug you pass to useQuery is replaced by the current store's.
  • Public or as the shopper. On the Bun storefront, load() and runtime data() send the public operations (catalogue, store, menus, promotions) without the shopper's cookie: their answer is the same for everyone, so the page stays cacheable. The customer* operations, and a gql() document with any top-level field outside the public list, run with the shopper's own cookie and make the page personal. useQuery runs with the shopper's cookie.
  • Account data never reaches the browser by query. useQuery refuses every customer* operation (404 NOT_FOUND). Read the shopper in load(), or use useCustomer() and useWishlist().
  • load() has a typed list. An operation outside it is a type error, and an unknown name resolves to null at run time.
  • gql() is a query you type yourself. Nothing checks it against the schema at build time. With a developer token (in bizzpocket dev --store), a gql() document must be a query whose top-level fields are all in the public list above, with no fragments at the top level, and naming no other store. Anything else is refused and the need is null. A gql() need is resolved with the page's other data; in a runtime block only the Bun storefront runs it. Keep gql() blocks static.

Developer-token scope

bizzpocket dev --store <slug> uses a developer token (bpdt_...) made by the store owner. It is deliberately small:

  • it reads the public data of one store, the one it was made for;
  • only the public operations above, and the page endpoint dev renders through;
  • never customers, orders, carts, checkout or wishlists, never drafts, never a write;
  • at most 120 requests a minute (past that, 429), and at most 32 operations in one page call;
  • it expires (7, 30, 90 days or 1 year), and the owner can revoke it at once.

It lives in your shell as BIZZPOCKET_DEV_TOKEN, never in the theme. Creating, rotating and revoking it are in tokens.md.


Caching and cookies

The storefront caches page HTML and shares it between shoppers. This is why a theme must keep personal data out of the server HTML. On the Bun storefront the rules are:

Page cache-control
a normal page, including one whose load(), runtime blocks or local fallback use only public operations public, s-maxage=60, stale-while-revalidate=600 (shared caches keep it 60 s, and may serve it stale for 10 minutes while they refresh it), vary: accept-encoding: the same HTML for every shopper
a page where load(), a runtime block or a local fallback ran a customer* operation (or a gql() document that is not all public), with or without a cookie; and account, order, login and signup pages private, no-store, vary: cookie
a preview (?bizz_preview=), a degraded page, or a page whose data did not finish in time no-store
/_bp/q/<op> (useQuery), with or without a cookie public, max-age=30, stale-while-revalidate=60, vary: accept-encoding (the shopper's session is never forwarded, so the answer is the same for everyone; errors are no-store)
theme JavaScript and CSS public, max-age=31536000, immutable (file names carry a content hash)

"Degraded" means some data failed or timed out, so the page shows less than it should. It is sent but never cached, so the next shopper gets a fresh try.

What it means for you:

  • Personal data belongs in the browser, through the hooks. A load() that reads only public operations keeps the page cached. A shopper-scoped call (a customer* operation, or a gql() document that is not all public) makes the page private, no-store for every request, guests included. Use one only when nothing else works.
  • Keep no state between requests. Page HTML must come only from the block's props and the ctx.query answers of the current request. load() and render must not keep anything at module level, such as a cache of query results. A customerMe answer kept in module scope would be rendered into a later page that uses only public operations, and that page is cached publicly.
  • Do not read or write cookies from a theme. The shopper's session is in customer_session, an httpOnly cookie your code cannot read, and it is set only for the store's own address. Use useCustomer() to know who is signed in.
  • Do not put shopper data in the URL. URLs are logged and cached. The host's own order tracking, for example, sends the phone number in a POST body, never in the URL.

Content security policy

Every storefront page carries a content security policy (CSP). On the Bun storefront it is:

style-src 'self' 'unsafe-inline'; script-src 'self' 'nonce-<random>' 'strict-dynamic'; object-src 'none'; base-uri 'none'

The production storefront sends the same style-src and script-src (plus 'wasm-unsafe-eval' when its captcha is turned on). The nonce is new for every response, and the storefront puts it on the scripts it writes itself (the island loader, React and the SIR runtime). Scripts those load may run ('strict-dynamic'). Nothing else may.

So, in a theme:

Works Is blocked
islands, and the npm packages bundled into them a <script> you write in a block, inline or with src
sir.* attributes inline event attributes in HTML (onclick="...")
React onClick and friends, inside an island a third-party script tag (analytics, chat widgets, pixels)
<script type="application/json"> data, such as sir.variantData() (it is data, not code) <object> and <embed>
inline style attributes and <style> a <base> tag

Third-party tags such as analytics are the storefront host's job: it loads its own, with its own nonce. A theme cannot add one.


Timeouts and caps

The ones you are most likely to meet. The limits reference has the full table.

What Limit What happens past it
load() on the Bun storefront 3 s the block renders with {}, the page is degraded
the whole page render on the Bun storefront 8 s missing data becomes null, the page is degraded
one storefront operation from the Bun storefront 5 s that need is null
one operation in the page endpoint 3 s that need is null
waiting for the last data before the headers 400 ms after the first HTML is ready the page is sent no-store instead of cacheable
useCartActions() / addToCart() 15 s the Promise rejects with TIMEOUT
useQuery variables 4 KB of JSON 413 VARS_TOO_LARGE; the hook says so without sending
useQuery cache in the browser 100 answers per tab the oldest is forgotten
f.richText() value 200,000 characters (or maxLength) the field's default is used
f.products() / f.categories() 50 items (or max) the rest are dropped
f.blocks() children 24 (or max) the rest are not rendered
containers inside containers 3 levels deeper children are not rendered
page.route.q (search text) 200 characters cut
page.route.filters 16 keys; names start with a letter (up to 40 characters); values up to 200 characters the rest are dropped
page.route.page up to 6 digits ignored
page.route.sort letters, digits, _ : . -, up to 40 characters ignored
a URL handle letters, digits, _ and -, up to 200 characters 404
global + block CSS inlined in a page (Bun storefront) 14 KB gzip the CSS is linked as a file instead
CDN picture width 1600 px, on the ladder 160 to 1600 rounded up to a rung (308 redirect), never larger
developer token 120 requests a minute, 32 operations a page 429, or the need is null
newsletter sign-ups, sign-in and sign-up rate limited per store and address (sign-in: 5 tries per 15 minutes) 429 / RATE_LIMITED, see forms.md

On the Bun storefront, a block that throws while it renders becomes an empty <section data-bp-error>. The rest of the page renders, and no error text reaches the shopper.

Next: migrate.md.