Guide
Security
Every page goes out with a CSP without unsafe-inline for scripts —on a static site too—, and with a server, secure headers, HttpOnly signed cookies, and same-origin forms only. Nothing to configure.
In mode: "server" —and in development— the kit applies
ascua-security to every response. A static site
carries at least the content policy, inside each page. There is nothing to
install or configure.
Content-Security-Policy
Every HTML page goes out with a closed policy:
default-src 'self'; script-src 'self' 'sha256-…'; style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; object-src 'none';
base-uri 'self'; form-action 'self'; frame-ancestors 'none'What matters is in script-src: no 'unsafe-inline'. The kit computes
the hash of each inline script over the HTML being sent —the shell's, for
example—, so what the page brings works and whatever slips in through a
template does not run. The island list is JSON and needs no hash; the script
that hydrates them goes with src.
- If the client carries WebAssembly, it adds
'wasm-unsafe-eval', without which the browser does not compile it. - If
baseis on another origin —a CDN—, that origin goes into the policy. - Styles allow
'unsafe-inline':styleattributes cannot be covered with hashes, and an injected style does not run code.
In development it goes as Content-Security-Policy-Report-Only: the browser
console warns about what would be blocked, without breaking anything.
On a static site
A static site sends no headers, so the build writes the same policy into every
page, as <meta http-equiv="Content-Security-Policy"> right after the
<meta charset>, with the hashes of its inline scripts. It is the one that
warned in development. Two differences from the header:
- It has no
frame-ancestors: in a<meta>the browser ignores it. If the site must not be shown inside someone else's<iframe>, whoever serves it has to set the header. - It only covers the pages of the kit's routes. An
.htmlthat Vite builds on its own —an entry inbuild.rollupOptions.input— goes out as it is.
URLs in attributes
The runtime does not write a javascript: URL that reaches href, src,
action, formaction or data through a hole, neither on the client nor in
the server's HTML (details). It is a
safety net, not validation: a third-party URL that should only be https: is
checked before rendering it.
Nor does it write a srcdoc that arrives through a hole if the <iframe> has
no sandbox in the template (details).
Headers
X-Content-Type-Options: nosniff |
The browser does not guess types; also for the files in dist/client/ |
Referrer-Policy: strict-origin-when-cross-origin |
Another site gets only the origin, not the path |
Cross-Origin-Opener-Policy: same-origin |
A window opened from another site cannot touch this one |
Strict-Transport-Security: max-age=31536000 |
Only if the request came over HTTPS, also behind a proxy (X-Forwarded-Proto) |
Whatever answers a POST or writes cookies also gets Cache-Control: private, no-store.
Forms
- Same origin only. An action runs only if the request's
Originis the site's —X-Forwarded-Hostbehind a proxy—. A form sent from another site gets a 403. Every browser sendsOriginon aPOSTand another site cannot forge it, so no tokens are needed in each form. - Limited body of 1 MiB: more is a 413.
Cookies
cookies.set writes them HttpOnly (not readable from JavaScript),
SameSite=Lax (they do not travel on another site's POST), Secure (except
on localhost) and Path=/. Any of them can be changed in the options.
cookies.setSigned and getSigned sign them with HMAC-SHA256 and the key in
the ASCUA_SECRET environment variable, 32 characters or more:
ASCUA_SECRET="$(openssl rand -base64 48)" node dist/server/index.mjsThe value travels readable —signing is not encrypting—, but a tampered cookie
reads as if it were not there. The secret comes from the environment and never
from the build: dist/server/ gets copied and uploaded. In development,
without ASCUA_SECRET, a random key per process is used.
Adjusting it
ascua({
site: {
mode: "server",
security: {
csp: { "img-src": ["https://cdn.example.com"], "frame-ancestors": null },
headers: { "Permissions-Policy": "camera=()" },
origins: ["https://admin.example.com"],
bodyLimit: 10 * 1024 * 1024,
},
},
});csp |
Adds sources to each directive; null removes it. false sends no policy |
headers |
Adds or replaces headers; null removes one |
origins |
Other trusted origins for actions |
bodyLimit |
Bytes accepted in a POST |
security: false turns it all off, and csp: false only the policy, also the
one in a static site's <meta>. The other options only apply with a server: a
static site sends no headers —whoever serves it sets them— and receives no
forms.