Server

Use your app's own Drizzle database for every block. Call it once at startup, before the first request.

The shared database: whatever setDatabase() was given, else a pool on DATABASE_URL, opened on first use.

The demo's viewer: whoever the candor_demo_user cookie names. With no cookie it's Riley, so a block works from a clean download; after signing out (the cookie is empty) it's nobody. Not authentication: anyone can set a cookie.

Replace the demo cookie with your auth. Call it once at startup, before the first request.

Whether a page on another site made the browser send request. Every route in the blocks and templates that changes something (POST, PUT, PATCH, DELETE) asks this first and answers true with crossSiteRefused(). Safe methods (GET, HEAD, OPTIONS) are never refused.

How it decides. Browsers say where a request came from. Sec-Fetch-Site is trusted when it's there: "same-origin", or "none" (the person typed the address), may go on; "same-site" (a sibling subdomain) and "cross-site" may not. Without it, Origin must name this app's host (X-Forwarded-Host behind a proxy, else Host). An origin listed in CANDOR_TRUSTED_ORIGINS (comma-separated, e.g. https://admin.example.com; compared as origins, so case, a default port and a trailing slash don't matter) may always go on. A request with neither header didn't come from a browser page, and goes on.

What it protects against: cross-site request forgery, a page elsewhere making a signed-in person's browser send a form or a fetch here with their cookies, so that it acts as them.

What it doesn't: a script running on the app's own origin (cross-site scripting); a caller outside a browser, such as curl or another server, which sends whatever headers it likes and is held back only by your auth; a route that changes something on GET; and browsers too old to send either header. It says nothing about who sent the request: that is getViewer().

What a route answers, with a 403, when crossSite() says another site's page sent the request.

Whether the demo cookie may say who is signed in: always outside production, and in production (NODE_ENV is "production") only when the app opts in with CANDOR_DEMO_AUTH=1. So a production deploy that never called setViewerSource() signs nobody in, rather than every visitor as the demo's first person.

Who sent request, by your auth; null when nobody is signed in. Until you set a source it's the demo cookie, except in production without CANDOR_DEMO_AUTH=1, where it's null for everyone (and the server log says why, once).

The signed-in person's name, which the blocks record as who did what; null when nobody is signed in.

What a route answers when nobody is signed in.

A template's sign-in route for the demo (api/session): GET says who is signed in and lists the demo's people, POST { email, code } signs that person in, DELETE signs out. Nothing is sent and nothing is checked beyond the code above; it sets the cookie demoViewer() reads (not HttpOnly, so the blocks' demo "signed in as" switches can still change it). In production without CANDOR_DEMO_AUTH=1 every method answers 403 with { error, demo: false } and lists nobody. options.allowed decides that instead of the environment.

Replace it with your auth's own sign-in (its route, or its hosted page) and call setViewerSource() with how your auth reads a request. The template's pages then need nothing else changed: they ask getViewer() through the API, and a 401 sends the person to the sign-in page.

What a person is told when something failed, without telling them how. A Refusal was written for them, so its message comes back as it is. Anything else (a database error, a setting that's missing, a bug) is logged on the server with a short reference, and the person gets sentence with that reference, which they can quote to whoever reads the log. Use it wherever an error's words would reach the browser: a route's answer (see errorResponse()), an agent stream's onError, a tool's result.

A route's answer to an error: a Refusal's own message with its status, or, for anything else, a 500 with sentence and a reference, the error itself going to the server log under the same reference (see errorText()).

For a Claude Agent SDK tool server, createSdkMcpServer(guardTools({ name, tools })): an error a tool throws reaches the model, and the browser that shows the tool's result, as errorText() says it, a Refusal as written and anything else as a fixed sentence with a reference (the detail goes to the server log). Without it the SDK sends any error's message as the tool's result.

For a Vercel AI SDK tool set, streamText({ tools: guardToolSet({ … }) }): an error a tool throws reaches the model, and the browser that shows the tool's result, as errorText() says it, a Refusal as written and anything else as a fixed sentence with a reference (the detail goes to the server log). Without it the model reads any error's message, and can repeat it to the person. The tool still fails, so the call shows as failed, and the route's onError says the same sentence rather than logging it twice. Tools without execute are left as they are; so is an error a streaming tool throws once its first result is out.

The AI SDK's approval signing, spread into streamText(): with CANDOR_APPROVAL_SECRET set, each approval request is signed, so a browser can't approve a call the server never asked about. Without it, nothing is signed.