Security model
This page gathers the rules spread over the guides, in one place. Each section links to where the details live.
The trust model
Section titled “The trust model”A droplet renders inside pages its server does not own, and those pages call it with whatever they like. Two things follow:
- The droplets server trusts the host page’s operator, not the request.
Everything a request carries is input:
host, the location headers, the props, the form body, the cookies. Render with it; never decide from it who may see or do what. That is the job of a session cookie or a token checked inhandleand the actions. - The host page trusts the droplets server like a third-party script. The fragment’s markup and the bundles run on its page with its origin’s rights. Embed droplets only from servers you would let run a script on that page.
Who sees what
Section titled “Who sees what”Embedding a droplet tells its server where it renders: the page’s URL,
path and query, in host. A host page’s server
that fetches fragments sends it (as "host" in a POST render,
or as Referer); the browser sends it with _data. A droplets server run
by someone else therefore sees the URLs of the pages it is embedded in,
query strings included. Do not embed droplets you do not trust on pages
whose URLs carry anything sensitive (a reset token, a search, an id).
What does not cross:
- the page’s query is never forwarded as props: the browser’s
_datarequest carries props from the element’s context only, and only a__cbcache-buster in its query; localsare never serialized into a fragment;- a private environment variable never reaches the browser unless a load returns it (see Server-only code).
The droplet location and host
Section titled “The droplet location and host”The droplet location is where the browser reaches the droplets server; it decides
the URLs a fragment writes about itself (its stylesheet, its Link
preloads, its action URLs) and the origins its form posts may come from.
It comes from x-droplet-location, else Forwarded, else
X-Forwarded-Proto with X-Forwarded-Host (and X-Forwarded-Prefix).
Anyone can send those headers, so:
- a header’s location is used only when its origin is the request’s own
or in
trustedOrigins/DROPLETS_TRUSTED_ORIGINS. An untrusted one is skipped (with a warning undervite dev), and never reaches an action URL. Without a list, forwarded headers count only when they name the request’s own origin; - it must be an
http:orhttps:URL; credentials, query and hash are dropped, and a path prefix with//,\,..,?,#or control characters, or over 256 characters, is dropped too; - of a forwarded header only the first value counts, the one the first proxy wrote;
- the proxy or host page’s server in front overwrites these headers with fixed values, or clears them, never passing on a client’s; and the droplets server is not reachable around that proxy.
With no trusted header, the location is the request’s own origin. See
x-droplet-location.
With location set, there is
nothing to trust: every request’s location is location, and no header is
read.
host (where the droplet renders) is taken from the request too: a render
body, then Origin, then the location’s origin. With trustedOrigins set,
a host outside it (and not this server) becomes the location’s origin.
With host set, it is that origin,
with the body’s path and query only when the body names a page on it.
hostFrom() checks a candidate the same way for a handle that reads
Referer. See host.
The browser does not take its location from the markup at all: the
elements load JavaScript, CSS and data from the URL the page loaded
/index.js from.
Trusting any location
Section titled “Trusting any location”"*" in trustedOrigins (or DROPLETS_TRUSTED_ORIGINS) trusts any
location a request’s headers name. The server allows it; under vite dev
and vite build it warns (a production server logs errors only):
trustedOrigins: "*" trusts any forwarded location; see https://dropletsjs.dev/guides/security/#trusting-any-locationWhat it opens up:
- Cache poisoning. One request with
X-Forwarded-Host: evil.examplegets a fragment whose stylesheet,Linkpreloads,droplet.url()and action URLs point atevil.example. Any cache in front that keeps it (a CDN ignoresVaryon these headers) serves it to everyone: their forms post to the attacker, their pages load the attacker’s CSS. - CSRF. The location’s origin counts as the server’s own in the
Origincheck and as a redirect target. A page onevil.examplethat also sendsX-Forwarded-Host: evil.exampleposts forms that pass the check.
It may be acceptable when no client can set these headers: a server on a
private network that only your own services reach, or behind a proxy that
strips every one of them and sets them itself, with the droplets server
reachable through nothing else. Even then, prefer listing the exact
origins in trustedOrigins. With "*", a header’s location is still
checked for a web URL and a clean prefix, nothing more.
Caching
Section titled “Caching”What each answer sends as Cache-Control:
| Answer | Cache-Control |
Set by |
|---|---|---|
/assets/* (but public/), client.js, style.css |
public, max-age=2592000, immutable |
fixed: files under /assets/ are content-addressed, and the routes carry the build’s hash as ?c=<hash>, so a deploy invalidates them |
/assets/public/*, the project’s public/ |
no-cache, with an ETag (a 304 while the file is the same) |
publicCacheControl: another value, or false for none; the ETag and 304 stay |
/index.js, /index.css |
no-store |
fixed |
/env.js |
public, max-age=600 |
DROPLETS_ENV_MAX_AGE (seconds, 0 for no-store) |
fragments and _data |
private, no-store, no-transform |
the load’s setHeaders, else fragmentCacheControl (false for none); handle has the last word; no-transform is always added |
| a render with a form’s result | private, no-store, no-transform |
fixed |
the 303 that carries a form’s result |
private, no-store |
fixed |
None of the files pass through handle (see
handle): anything under /assets/ is public to
whoever has its URL. The import map is not cached by the server.
How /index.js picks up a new build
Section titled “How /index.js picks up a new build”/index.js is a small file of the build that imports the entry client
under a name unique to the build, relative to its own URL:
import "./env.js";import "./assets/index.C-iXBKI0.js";
((globalThis[Symbol.for("droplets.servers")] ??= {})["my-widgets:a151d9"] ??= {}).origin = new URL(/* @vite-ignore */ ".", import.meta.url).href.replace(/\/$/, "");- Always fresh, mostly cached. A page that loads
/index.jsalways learns about the newest build; on a reload only those few bytes go over the network, and the entry comes from the cache. /env.jsfirst. The imports are static, so the browser fetches both at once and runsenv.jsfirst.import "./env.js"is there only whensrc/env.tsdeclares runtime public variables ({ public: true }withoutstatic):/env.jshands the page their current values, takes nothing from the request, and a shared cache may keep it.handlenever runs for it.- Where the elements load from. The last line records where the page
loaded
/index.jsfrom, prefix included: the elements load from there. It runs after the entry; an element that connects before it finds the same location from the entry’s own URL.$droplets/dropreads the server’s origin from the same record. - One record per server and build, under
<element>:<build>. Servers sharing a page already need distinctelementnames; the build hash tells two builds of one server apart. - Served by the droplets server.
/index.jsmust come from the droplets server, under its prefix: its own URL is what the browser trusts. A CDN in front of it, pulling from the server at the same URL, works; a copy uploaded elsewhere would make the elements load from there.
Fragments and _data
Section titled “Fragments and _data”They depend on the request’s host, props and cookies, so a shared cache
must not keep them by default. A droplet that is the same for everyone
opens itself to caches with setHeaders in
its load, which replaces the default on the fragment and on _data.
- Only what rendered. The default is for
2xxanswers: an error answer, a load that failed, a404, a405and a redirect carry none of it (nor the load’s), so afragmentCacheControlmeant for content never keeps a failure. An error answer still carriesCache-Control: no-transform. no-transform, always. Every fragment and_dataanswer carries it, added to whateverCache-Controlit has (the default, the load’s,handle’s) when it is missing, never twice, so no proxy rewrites a fragment (see HTML rewriters). A redirect and a form action’s JSON answer are left as they are.- Prerendered renders are served with the headers their load set at build.
Vary. Every fragment and_dataanswer carriesVary: x-droplet-location, forwarded, x-forwarded-host, x-forwarded-proto, x-forwarded-port, x-forwarded-prefix, origin, after anyVarythe load set; withlocationset,Vary: originalone, since no location header decides them.accept-encodingcomes last: the server gzips the answer for a client that takes it. These are the headers the answer’s URLs andhostcome from, so in a cache that honorsVarya request with a spoofed one lands in an entry of its own. CDNs mostly ignoreVaryon custom headers, though: what keeps a spoofed location out of a shared cache is that the server ignores it unless it is on the allow-list.
Cache fragments in your host page’s server if their content allows it.
CSRF: the Origin check
Section titled “CSRF: the Origin check”A page on another site can make a browser post a form to your server with
the user’s cookies. A POST, PUT, PATCH or DELETE to /droplets/*
or /api/* whose body is form-urlencoded, multipart or text/plain, or
that has no content type, answers 403 before handle runs unless its
Origin is the server’s own (or its location’s), in trustedOrigins, or
host of the config (the import map
paths are checked the same way); "*" in trustedOrigins lets every
request through:
- a form post without an
Origin, or withOrigin: null(a page withReferrer-Policy: no-referrer), is refused; - a request without a content type and without an
Originpasses: that is another server calling, not a browser; - JSON bodies and
GETs are not checked: a cross-origin JSON post needs a CORS preflight, whichcorsanswers.
csrf: { checkOrigin: false } turns it off. See
Form posts.
A request event.fetch sends to this server
is checked the same way: it carries the outer request’s Origin, so a form
post from a request the check let through passes, and one from a request
without an Origin sets origin itself or is refused.
When the host page and the droplets server are on different origins, the
browser needs permission to load /index.js and /droplets/<id>/client.js
as modules, to POST to /droplets/<id>/_data with a JSON body, and to
load fonts. Set cors in droplets.config.ts: true, or an origin list.
Stylesheets and images need no CORS. On Cloudflare the build’s files
(/index.js, /assets/*, client.js, style.css) are answered by the
static assets with Access-Control-Allow-Origin: * from the generated
_headers, whatever cors says; cors covers what the Worker answers.
With CORS on, Access-Control-Expose-Headers always includes Link and
x-droplets-build, on top of any exposeHeaders you pass. A host page’s
server that proxies the droplets routes under its own origin
(the paths) needs no CORS at all.
cors: true sends Access-Control-Allow-Origin: * on every route, /api/*
and _data included, and warns once under vite dev. For anything that is
not public, list the hosts instead (cors: { origin: [...] }): with *,
any page can read what an employee’s browser can reach on an intranet
server. The same goes for server.cors in vite dev, which otherwise lets
any site you visit read the dev server’s sources. See
cors.
Cookies
Section titled “Cookies”- Defaults:
httpOnly: true,sameSite: "lax",secure: trueexcept over plain HTTP tolocalhostor a loopback address.pathis required and absolute.sameSite: "none"withoutsecure: truethrows. - What
handle, a+server.tshandler or an action sets withevent.cookiesgoes out asSet-Cookieon the response that answers the request: the fragment,_dataor the endpoint, also an error, a redirect or a response the handler built itself. - A droplet’s
loadandtransformonly read cookies:cookies.set()andcookies.delete()throw there. - Using cookies while prerendering throws
CookiesInPrerenderErrorand stops the build.
Cookies reach the browser in one of two ways:
- same origin: the host page’s server proxies the droplets routes under its own origin (the paths); the browser sends and receives them directly, as first-party cookies;
- forwarded by the host page’s server: a fragment it fetches
delivers its
Set-Cookieto that server, not to the browser. That server passes it on with its page, and forwards the browser’sCookieheader when it fetches fragments. It never passes on aDomainattribute: the cookie belongs to the host page’s own origin.
A host page’s server fetching fragments does not follow redirects
(fetch(url, { redirect: "manual" })): a redirect is the droplet’s answer,
for that server to pass on, and following it would make it
request a URL someone else chose.
Limits
Section titled “Limits”Bodies over a limit answer 413 before handle runs: 1 MB of JSON, 1 MB of
form-urlencoded or text/plain, 10 MB of multipart or anything else. An
x-droplet-props header over 8 KB answers 431. A body without a
content-length is held in memory while it is counted, so mind the
multipart limit times your concurrency. limits in droplets.config.ts
changes them. See Body limits.
Server-only code
Section titled “Server-only code”$droplets/serverand$droplets/env/privatecan only be imported from server files: names with.server.in them, any extension (+droplet.server.ts,hooks.server.ts,db.server.tsx),+server.*routes and files under a folder namedserver/(observer.tsandserver-utils/x.tsare not). Any other project file that imports them fails the build.- Server files never reach the browser. A
*.server.*file, a+server.*route or anything under aserver/folder that client code reaches, directly or through other modules, failsvite buildand is refused byvite dev, with the import chain. Case does not matter:Server/,SERVER/anddb.Server.tscount as server files. The same holds for a server file named as a file rather than imported as a module:new URL("./keys.server.json", import.meta.url), a CSSurl(), a?url,?rawor?inlineimport fails the build whether Vite would inline it as adata:URI or emit it, andvite devanswers 403 when the browser asks for one (/src/lib/server/keys.txt). A universal+droplet.tsruns in the browser and cannot import them. Dependencies innode_modulesare not checked: keep secrets in your own server files. - Load results are inlined into the page. Never return a private value, a token or a password hash from a load.
- Without
handleErrorin+droplet.server.ts, a production server sends a failed load’s error page onlyInternal Error; what a driver or a query said stays in the log.
Form actions without JavaScript
Section titled “Form actions without JavaScript”A form posted without JavaScript is answered with a 303 back to its page,
the action’s result signed in the page’s query
(Post/Redirect/Get).
What that token is, and is not:
- Signed, not encrypted.
base64url(JSON { status, data, exp, action }), a., and an HMAC-SHA256 keyed withDROPLETS_SECRET. Anyone with the URL can read it: it is in history, logs andReferers. Return field names and message codes, never the submitted values or secrets. - Bound to one droplet, one build and one page. The MAC covers the droplet, the build, the page’s origin and path, and the JSON. A result minted for one page is ignored on any other.
- Short-lived and small. Five minutes, 2 KB; over 2 KB,
datais dropped andformisundefined. - Checked before it is read. Length and shape, then the MAC
(
crypto.subtle.verify), then plainJSON.parseinto objects without prototypes, then the expiry and an action the droplet still exports. Anything else is ignored, as if there were none. - Display only. Anyone who can post the form can make a URL that shows a
result to someone else for five minutes, and a reload shows it again.
Never decide access from
form, and do what must happen once in the action. - Back only to trusted pages. The page, and any
redirect()target (for an enhanced form’s JSON answer too), must be on the server’s own origin, intrustedOriginsorhostof the config, by exact origin,http:orhttps:only."*"never counts: it lets every origin post, never sends the browser anywhere. A post with no page that passes answers400before its action runs. - One secret per build.
DROPLETS_SECRETis set up as in Actions: 32 or more random bytes, the same on every instance, kept as a secret.
Redirects
Section titled “Redirects”Every redirect() the server answers passes one bound, wherever it was
thrown: a droplet’s load or transform, handle, a form action (its JSON
answer included) or a +server.ts handler.
- Resolved first. The target becomes an absolute URL: against
host(the page the droplet renders on) for a droplet’s code,handleand an action; against the request’s URL on the droplet location for an endpoint. - Answered only on known origins. Its exact origin must be the
server’s own, its droplet location’s, in
trustedOrigins(orDROPLETS_TRUSTED_ORIGINS) or the configuredhost;http:orhttps:only, without credentials."*"intrustedOriginsnever counts here. - Anything else answers
400, with nolocationand one line in the server log: an off-site URL,javascript:,//evil.example. - A reported
hostis no way around it. Without atrustedOriginslist,hoststands as an untrustedOriginreported it; a relative target resolved against it is refused the same way.
Request input
Section titled “Request input”Droplets follows a few rules for everything a request brings, and your
actions and +server.ts handlers should too:
- Plain data only. Props arrive as strings from the query, or as JSON
from a body or
x-droplet-props, and go through the props schema before any load. An action reads its own body and checks each field’s type; nothing of the body is merged into props or anything else. An action returns plain JSON (object literals, arrays, strings, finite numbers, booleans,null): aDate, a class instance or a function answers500. A signed form result is parsed with plainJSON.parseand copied into objects without prototypes,__proto__dropped; props andformfrom a JSON body orx-droplet-propsare copied the same way, as ordinary objects without an own__proto__key and at most 64 levels deep; enhanced forms read an answer with own keys only. - Own properties only. An action name is looked up as an own function of
a plain
actionsobject, and must match[A-Za-z_][\w-]*:__proto__,constructorortoStringanswer404. Manifest and registry lookups useObject.hasOwnor aMap. In your code, read a request-chosen key withObject.hasOwn(or aMap), never withobj[key]on an ordinary object. - Code is resolved before the body is parsed. The
Origincheck and the body limits run first; then the droplet, itsactionsexport and the action’s name are resolved; only then does the action read the body. A droplet withoutactionsanswers405with its body never read. A request never chooses which code runs through anything it sends in a body.
Two more places where request data meets HTML:
transformwrites into HTML withhostand props from the request: escape what you splice in, and pass the replacement as a function. Seetransform.- Build-time renders hold
hostand the location as tokens that carry a per-build nonce, so content cannot fake one (none at all whenlocationandhostare both set). They are filled with HTML escaping: use them in text and attribute positions, not inside an inline<script>or<style>. Seehostat build.
Host-asserted identity
Section titled “Host-asserted identity”A droplets server with no login of its own can take the visitor’s identity from the host page’s server, when that server already has a login. The WordPress tutorial does this: a logged-in admin’s requests carry a signed assertion, and the droplets server treats it as the admin. It is safe only under the conditions in When this pattern is fine, all of them: the host page’s server the only way in and stripping the assertion header, a secret per direction, an assertion bound to one request, unsafe requests checked on both sides, writes back allow-listed. Where the droplets server is reachable from the internet, or the host page’s server cannot strip headers, use a login of its own instead, as the shop does.
What the log holds
Section titled “What the log holds”A production server logs errors only, with console.error; the warnings
above (untrusted locations, "*", a missing DROPLETS_SECRET, cors
allowing every origin) show under vite dev and are not in a production
bundle. The list is in Logging.
For hosts
Section titled “For hosts”A host page’s server that fetches fragments follows the five-line security checklist on Any other stack, with the headers it sends and passes on.