Authentication & Security

The authentication model is small on purpose: one shared editor password, signed session cookies, and a CSRF header on every mutation. This page covers all three plus the production checklist.

The model

One editor password Anyone with CARET_EDIT_PASSWORD can edit. No user accounts in embedded mode.

HMAC-signed session cookies 12h TTL, timing-safe compare, rotatable via secret rotation.

CSRF header on every mutation x-caret-request: 1 forces a CORS preflight on cross-origin POSTs.

Note

If the threat model needs more (per-user auth, audit logs, IP whitelisting, MFA), wrap the integration with your own middleware or wait for cloud mode.

Setting the editor password

.env

CARET_EDIT_PASSWORD=long-random-passphrase
CARET_SESSION_SECRET=different-long-random-string

Variable	What it does
CARET_EDIT_PASSWORD	Checked on POST /api/cms/auth/login with constant-time compare
CARET_SESSION_SECRET	Signs session cookies — always set in production
EDIT_PASSWORD	Fallback for backward compat (prefer the prefixed version)

Generate random values:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Run the command twice — once for the password (or pick a passphrase you’ll remember), once for the secret.

Don't ship without a session secret

If CARET_SESSION_SECRET is unset, the integration falls back to a default secret that anyone can forge. Always set this in production.

How the session cookie works

On POST /api/cms/auth/login with the right password:

1. The server builds a payload: { exp: now + 12h }.
2. Base64url-encodes it.
3. Signs with HMAC-SHA256 using CARET_SESSION_SECRET.
4. Sets caret_session=<payload>.<sig> as HttpOnly; SameSite=Lax; Path=/; Secure (Secure only over HTTPS).

On every authenticated request, the server:

1. Reads the cookie.
2. Splits payload and signature.
3. Re-signs the payload with the secret.
4. Compares the two signatures with crypto.timingSafeEqual.
5. Verifies exp > now.

Verification was hardened to:

• Decode signatures from base64url (rejects malformed input cleanly)
• Refuse empty signatures (would otherwise compare against zero-length expected)
• Catch decode errors and reject (rather than throw)

There’s a regression test at tests/unit/auth-token.test.ts.

CSRF defense

Cookies use SameSite=Lax, which blocks cross-origin top-level POSTs. But same-origin XSS (or any future cross-origin fetch with credentials) could still post. CaretCMS adds a second layer:

The rule

Every mutating route requires x-caret-request: 1 as a request header.

Routes that enforce it:

• POST /api/cms/mutate
• POST /api/cms/history
• POST /api/cms/upload

Why this works:

Mechanism	What it blocks
Custom header on cross-origin fetch	Forces a CORS preflight that fails (you don’t ship permissive CORS)
HTML form action	Forms can’t set custom request headers
Same-origin XSS	Could still set the header — but if you have XSS, you’re already compromised

The shipped editor sets the header automatically. Custom clients need to add it:

curl

curl -X POST http://localhost:4321/api/cms/mutate \
  -H 'Content-Type: application/json' \
  -H 'x-caret-request: 1' \
  -H 'Cookie: caret_session=<token>' \
  -d '{ ... }'

fetch

await fetch('/api/cms/mutate', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'x-caret-request': '1',
  },
  body: JSON.stringify({ /* mutation */ }),
});

Missing it returns:

{
  "error": "Missing required request header",
  "detail": "Send 'x-caret-request: 1' on mutating CMS requests."
}

with HTTP 403.

Auth endpoints

Route	Method	Purpose
/api/cms/auth/login	POST	{ password } — sets the session cookie
/api/cms/auth/session	GET	{ authenticated: boolean } — checked by the editor bootstrap
/api/cms/auth/logout	POST	Clears the session cookie

Detail	Value
Session cookie name	caret_session
Default TTL	12 hours
Override TTL	CARET_SESSION_TTL_HOURS

Production checklist

Run through this before any production deploy:

• CARET_EDIT_PASSWORD set to a long random value (or removed if you’re disabling editing in prod)
• CARET_SESSION_SECRET set to a different long random value — never commit it
• HTTPS only — Secure cookies require it; logged-in editors leak session tokens otherwise
• output: 'server' (or hybrid with prerendering off on /admin and /api/cms)
• Don’t expose the editor on a public preview URL without lockdown — the entire editor is gated by one shared password
• If you don’t want editing in production, set enableAdmin: false and enableInlineEditor: false

If you want editing on production but not on a public preview, set enableAdmin and enableInlineEditor from import.meta.env so they vary by environment:

caret({
  enableAdmin: import.meta.env.MODE === 'editing',
  enableInlineEditor: import.meta.env.MODE === 'editing',
})

Threat model

What this protects against

• Drive-by CSRF (custom header forces preflight)
• Session forgery (HMAC + secret + timing-safe compare)
• Password brute-force on a network with rate limiting (the server itself doesn’t rate-limit — put a layer in front)
• Prototype-pollution attempts in field paths (rejected at the mutation layer)

What this doesn't

• A leaked CARET_EDIT_PASSWORD — anyone with it can edit. Rotate by changing the env var. To invalidate existing sessions, also change CARET_SESSION_SECRET.
• XSS — if attacker JS runs in your editor’s browser, all bets are off.
• A leaked CARET_SESSION_SECRET — anyone can forge sessions. Treat it like a private key.
• Network-level attacks — use HTTPS and a CDN/WAF.

Rotating credentials

To kick all editors out and invalidate every session:

1. Change CARET_SESSION_SECRET (existing cookies fail signature verification).
2. Optionally change CARET_EDIT_PASSWORD (forces a fresh login).
3. Redeploy.

There’s no per-user revocation because there are no users.

Next steps

Deployment Production hardening per host.

Configuration enableAdmin, enableInlineEditor flags.

API Reference Auth endpoints in detail.