Skip to content
carameldocs · 0.23.0
Browse documentation
Reference / Security defaults

Safe by default.

What Caramel checks on every request, and what your application must keep doing.

ContractValue
Release0.15.0
NeedsAPP_ORIGIN as an HTTPS origin without a path; APP_SECRET of at least 32 bytes
CoversCSRF, sessions, headers, escaping, ingress, redirects, static files, errors
Proved byfrappe corretto: forged requests answer 403

Learning it for the first time? Best practices shows which protections to keep on. This page lists every default.

Limits at a glance

LimitValue
CSRF token valid for24 hours
Session cookie valid for14 days from its last write
APP_SECRET, at least32 bytes
Session cookie, at most4096 bytes
Default request body2 MiB
limit: range1 byte – 64 MiB
Uploaded files budget64 MiB
Values and files per request4,096 values, 128 files
Outbound call5 s connect, 30 s read, 60 s in all, 10 MiB response

Browser writes need a token and an origin

The submitted token must match the __Host-caramel_csrf cookie, compared in constant time.

ConditionOutcome
POST, PUT, PATCH or DELETE on a route with the default ingresschecked
A request that matches no routechecked too
Origin that does not equal the application’s origin exactlyanswers 403
A token that does not match the __Host-caramel_csrf cookieanswers 403
A failed checkanswers 403 “This form has expired or came from another site. Reload the page and try again.”
A JSON member named _csrfis not a token
A valid cookiekeeps its token
No valid cookiea new token is issued
APP_ORIGIN that is not an HTTPS origin without a pathraises ArgumentError
APP_SECRET under 32 bytesraises ArgumentError
A _method override on a route that reads its body differentlyanswers 405

Forms send the token in a hidden _csrf field. htmx and fetch send it as X-CSRF-Token. The generated layout puts the header on every htmx request, and generated forms carry the field.

app/views/layouts/application.cr · generated layout excerpt
body "hx-boost:inherited": "true", "hx-target:inherited": "#content", "hx-swap:inherited": "innerMorph",
  "hx-headers:inherited": {"X-CSRF-Token" => @csrf_token}.to_json do
app/views/books/form.cr · generated form excerpt
form class: "book-form", action: @action, method: "post" do
  input type: "hidden", name: "_csrf", value: @csrf_token
  input type: "hidden", name: "_method", value: @method unless @method == "POST"

A token is a timestamp, a random nonce and an HMAC-SHA256 signature. Every HTML response sets the cookie with Secure, HttpOnly, SameSite=Lax and Path=/.

Sessions are signed and held by the browser

session is a Hash(String, String) stored in the __Host-caramel_session cookie. The cookie holds base64url JSON, the unix second it was signed and an HMAC-SHA256 signature. Its key is derived from APP_SECRET for this one purpose; the keys derived from APP_SECRET_PREVIOUS verify, and never sign.

Inside an action · signing in
def handle(contract : Contract) : Caramel::Response
  session["user_id"] = contract.user_id
  redirect_to "/books"
end
ConditionOutcome
A cookie that is malformed or wrongly signedreads as an empty session
A cookie signed before 0.20.0, without an issue timereads as an empty session
A cookie signed more than 14 days ago (session_max_age in Caramel.build)reads as an empty session
A cookie signed more than a minute ahead of this host’s clockreads as an empty session
A CSRF signature offered as a session signaturedoes not verify, because the key is derived for one purpose
A response when the session did not changesets no cookie, so the window runs from the last write
sign_outclears the session; the response deletes the cookie, and a saved copy reads until its window ends
A session over 4096 bytesraises Caramel::Session::Overflow
APP_SECRET changed, the old value in APP_SECRET_PREVIOUSreads every session cookie and CSRF token as before; a changed session is re-signed with the new secret; debug tokens end
APP_SECRET changed, no previous secretreads every session cookie as empty and fails every outstanding CSRF token; debug tokens end
A route whose ingress sets csrf: falsereads an empty session and never saves it

The cookie has the same Secure, HttpOnly, SameSite=Lax and Path=/ attributes. It has no Max-Age, so it ends with the browser session or 14 days after its last write, whichever comes first; an action re-signs it only when it changes the session. There is no server-side store, so sign_out cannot end a copy of the cookie before its window does. Revocable sessions → Keep ids in the session and records in the database.

The session is readable, though not editable, by anyone holding the cookie. Store no secrets in it.

Every response carries the same headers

Caramel adds three headers to every response, including static files and error pages, and a fourth when serve runs in production.

HeaderEffect
X-Content-Type-Options: nosniffBrowsers keep the declared content type
Referrer-Policy: same-originOther sites receive no referrer
Content-Security-Policydefault-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; object-src 'none'
Strict-Transport-Security: max-age=31536000Browsers use HTTPS for this host for a year; serve sends it when CARAMEL_ENV is production or unset, never in development or test, and never with includeSubDomains or preload
ConditionOutcome
Inline scripts, inline styles and framingblocked by the policy
Caramel.content_security_policy.add("script-src", "https://js.stripe.com") in config/application.cr, before the application is builtchanges the policy of every response
content_security_policy.add("frame-src", "https://player.example") in an actionchanges the policy of that response only
add to a -src directive the policy lacksstarts from default-src’s sources, so 'self' stays; adding a source also removes 'none'
set and deletereplace a directive’s sources, or remove the directive
add with no source, a directive name that is not lowercase words joined by hyphens, or a source with a space, a comma or a semicolonraises ArgumentError
csp_noncereturns a new nonce for this response and adds 'nonce-…' to its script-src and style-src
A fragment htmx swaps into a page loaded earlieris governed by that page’s policy; a nonce covers only the response that carries it
A Content-Security-Policy header an action sets itselfis kept
HTML and JSON responses from actionsalso send Cache-Control: no-store
Host that differs from APP_ORIGIN’s host and portanswers 421 “Unknown project host”
Forwarded headersgrant no trust
A path that does not start with /answers 400

Put scripts and styles in files under app/assets/, which Frappé publishes to public/assets/, as the generated layout does; an edit made in public/ by hand stops the next publish with Asset output conflict.

Views escape text and attributes

Blueprint views escape text and attribute values. The escape covers &, <, >, " and '. markup { … } builds a small fragment with the same escaping.

ConditionOutcome
A Caramel::HTML::Safe or safe(...) valuewritten as it is
raw with any other valuefails compilation
page(title, body) with a plain String bodywritten as it is; pass a view or markup instead, or escape with Caramel::HTML.escape
A value used as a URL, script or stylenot made safe by escaping; validate a stored link before writing it into href
A translated message with a Caramel::HTML::Safe placeholderbecomes safe HTML: its catalog text and other values are escaped, and only the safe values are written raw
A translated message otherwisecatalog text stays plain text, which the view escapes
Inside an action · an escaped fragment
morph "#status", with: markup { span { "Status #{count}" } }

Wrap a string in Caramel::HTML::Safe only when you built or trust all of its HTML. Escaping protects HTML text and quoted attributes only. Translate messages →

Ingress loosens one route at a time

An action’s ingress declaration changes how its route reads the request. Turning CSRF off needs an authenticator. A tenant route needs one too, or ingress open: true to serve anyone in the tenant; open: never combines with authenticate:, and frappe routes prints it as [open].

An action declaration · from Caramel::Action’s documentation
ingress body: :raw,
  limit: 256.kilobytes,
  csrf: false,
  authenticate: :signed?
ConditionOutcome
csrf: false without authenticate:fails compilation with “ingress csrf: false needs authenticate: :method? that verifies a credential a browser does not attach on its own, such as a signature or a bearer token”
A subtype that redeclares ingress without its parent’s authenticator, or with open: true under itfails compilation
A route in the tenant block whose action neither authenticates nor declares open: truefails compilation
An authenticator that returns falseanswers 401 “Unauthorized”, before the contract binds
A body over its limitanswers 413
An unsupported media typeanswers 415
More than 4,096 values or 128 filesanswers 413
body: :rawkeeps the exact bytes in raw_body
Uploaded filesstored only for a route whose contract has a Caramel::UploadedFile field

A body’s default limit is 2 MiB, and limit: sets 1 byte through 64 MiB. Uploaded files have their own 64 MiB budget. A request may send at most 4,096 values and 128 files. Receive a signed webhook →

Redirects and outbound calls name their destination

redirect_to accepts only a local absolute path. redirect_external is the explicit way to another site: it accepts an absolute http or https URL with a host and no credentials, whitespace, control characters or backslashes.

ConditionOutcome
redirect_to with a path starting //, or holding a backslash or control characterraises ArgumentError
redirect_to from an htmx requestanswers 200 with HX-Location instead of 303
redirect_external with a URL that is not absolute http or https with a host, or that holds credentials, whitespace, control characters or backslashesraises ArgumentError
redirect_external with a status other than 301, 302, 303, 307 or 308raises ArgumentError
A URL saved with validate_urlcan always be redirected to, because Caramel::ExternalURL.valid? backs both
A host in Caramel::Outbound that resolves to a loopback, private, link-local, multicast or reserved addressraises Caramel::Outbound::Blocked before connecting; Caramel::Outbound.allow_private = true turns the check off, and a proxy skips it
An outbound response over 10 MiBraises Caramel::Outbound::TooLarge and closes the connection
An outbound call still running after 60 sraises IO::TimeoutError
Inside an action · leaving for a stored link
def handle(contract : Contract) : Caramel::Response
  return not_found unless Caramel::ExternalURL.valid?(contract.url)
  redirect_external contract.url
end

Caramel::Outbound.get, post and request call third-party APIs under the same URL rule. They connect within 5 seconds, read within 30 and finish within 60, to the address the host resolved to, so a DNS answer cannot change between the check and the connection. The whole response is read into memory, at most 10 MiB.

Inside an action · an outbound call
headers = HTTP::Headers{"Authorization" => "Bearer #{ENV["API_TOKEN"]}"}
reply = Caramel::Outbound.get("https://api.example.com/status", headers)

Static files stay inside public/

Files in public/ are served before routing, after the host check. Caramel refuses a path that would leave that directory, never serves a hidden file, and hands every other hidden path to the router. ADR 0038 ↗ records the rules.

ConditionOutcome
A malformed percent escapeanswers 400
A decoded path with a NUL byte, a backslash, or a . or .. segment, such as encoded traversal like %2e%2eanswers 404
A path with a hidden segment, such as .env or .git/config, outside .well-knownroutes to the router, which answers 404 unless a route matches
A first segment of exactly .well-knownis served from public/.well-known/ like any file, or routed when no file matches
A file whose real path, after symbolic links, lies outside public/answers 404
A method other than GET and HEADanswers 405 with Allow: GET, HEAD
A GETsends the file as a stream with its Content-Length, ETag and Last-Modified
A name with a three-part version, such as htmx-4.0.0.min.jscarries Cache-Control: public, max-age=31536000, immutable
Any other filecarries Cache-Control: no-cache
A request whose If-None-Match names the ETag, or whose If-Modified-Since is not older than the fileanswers 304 with no body
A Range headeris ignored; the whole file is sent
A file that cannot be readanswers 500 Something went wrong. with Cache-Control: no-store, reported to Crema

Errors reveal a reference, not details

ConditionOutcome
An unhandled exceptionanswers 500 “Something went wrong. Reference: …” with an X-Request-ID header and Cache-Control: no-store
The exception messageis not logged, because it can hold connection URLs or form values; the log keeps the request id, the error’s class and a fingerprint
A build without -D caramel_developmentholds none of the error page’s code; a check builds both modes and confirms it
A development build run without CARAMEL_ENV=developmentshows no error page

The development error page is compiled only with -D caramel_development, which frappe dev sets. It redacts the values of environment variables named like secrets, passwords, tokens, API keys or database URLs, PostgreSQL URLs, and name=value credentials.

Not covered Your application still owns the rest

Caramel checks where a request came from, not what the signed-in user may do. Authorization for each record, rate limits, secret storage and the URLs you write into pages stay in your application.

Prove it

Prove the defaults

Terminal · inside the application
frappe corretto spec/requests/books_spec.cr

Passing: Every example passes. The generated spec’s forged X-CSRF-Token and foreign Origin requests answer 403, and its sample title <title> is checked as escaped text.