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 base is on another origin —a CDN—, that origin goes into the policy.
  • Styles allow 'unsafe-inline': style attributes 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 .html that Vite builds on its own —an entry in build.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 Origin is the site's —X-Forwarded-Host behind a proxy—. A form sent from another site gets a 403. Every browser sends Origin on a POST and 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:

sh
ASCUA_SECRET="$(openssl rand -base64 48)" node dist/server/index.mjs

The 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

ts
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.