SiteConfig schema

SiteConfig is the site-scoped, mutable config tier: domains, transport security, visitor access control, handler caps, compression, and the gateway. It is stored as JSON in the KV (not in a deployment manifest), so it changes independently of content and does not roll back with a deployment. Most of it is managed through subcommands rather than edited by hand.

The tiers, contrasted:

Top-level fields

domains

The hostnames a site answers to (virtualhost routing). See Serve a custom domain.

security

Site-tier transport security. Off by default; opt in once TLS is in front (directly or via a terminating proxy). The effective scheme is read from X-Forwarded-Proto behind a trusted proxy. See Harden the security posture.

hsts

access

Visitor access control — WAF, IP rules, rate limiting, basic auth, trusted-proxy handling. This is the full mechanism for restricting who may view a site; it is separate from control-plane RBAC. Managed with boatramp access and documented in Restrict visitor access.

handlers

Site-scoped handler policy: the capability allowlist and resource caps a deployment’s requested handler config is intersected against at activation (deny by default). None disables handlers for the site entirely.

A handler that requests an import not in allow_imports, or exceeds a cap, is rejected at activation — not at request time. See Handler host bindings.

handlers.cache

Host-level response cache: a cacheable GET/HEAD response is served for a later identical request without re-instantiating the handler. Opt-in per response, driven by the handler’s own Cache-Control; never caches a private response (no-store/private/no-cache, a Set-Cookie, Vary: *, or an Authorization request without public/s-maxage). Entries are keyed by the request’s project-qualified scope, honor Vary, and expire by TTL. Backed by the site’s KV store. See Cache handler responses.

handlers.graphql

GraphQL edge features. Off unless present + enabled. See Serve a GraphQL API.

Renamed in v0.6.0 (breaking). The old safelist: bool toggle is now enforce_safelist: bool — the enforcement switch, made distinct from the new declarative source of operations (safelisted_ops / safelisted_ops_path). Rename the field in any site config that set the old safelist:.

handlers.cookie_auth

Browser cookie session auth. Off unless present. A request carrying the named cookie but no Authorization header is authenticated from the cookie value — boatramp injects it as the app bearer everywhere the header bearer flows (the Authorization header always wins). boatramp only reads the cookie; the app sets, refreshes, and verifies it. Set the cookie HttpOnly; Secure; SameSite=Lax with a __Host- prefix. See Authenticate a browser with a session cookie.

handlers.tenancy

The site’s in-site tenancy decision — how the host scopes sql/orm row access across sub-tenants sharing one database. Absent (None) means undeclared: refused at activation for a sql/orm-importing site under the multi-tenant posture (which requires an explicit decision), treated as disabled under single-tenant/dev. Three shapes (a tagged mode):

{ "mode": "disabled" }

Deliberately no in-site tenancy — plain queries (the project = database boundary is the whole isolation). The explicit “single-tenant / no tenancy” declaration.

{ "mode": "scoped",
  "column": "tenant_id",
  "sources": [ { "kind": "token", "claim": "tid" } ],
  "read":  "own",
  "write": "own" }

In-site sub-tenancy on column, resolving “own” from the first applicable sources entry, at per-axis access grants. In project.cfg / apply.cfg RON the canonical spelling is (mode: "scoped", column: "tenant_id", sources: [(kind: "token", claim: "tid")], read: "own", write: "own").

Each TenantSource is {"kind":"token","claim":"tid"} (a verified JWT claim, claim default tid), {"kind":"domain"} (the routed domain’s contexts tag), {"kind":"signed_context"} (a host-verifiable envelope on an async job/message — the async-lane “own”), or {"kind":"none"} (anonymous — an “own” grant then fails closed).

AccessMode is one of none (deny), null (the tenant_id IS NULL shared baseline only), own (the resolved tenant), own_or_null (both), or all (cross-tenant — default-deny, gated by the allow_cross_tenant_db posture ceiling; capped to own when off). own_or_null on the write axis degrades to own (a write never touches the shared baseline). A top-level function’s own tenancy block narrows within this site ceiling. Full model: Isolate tenants in one database.

{ "mode": "target",
  "via": [ "domain" ],
  "public": "storefront",
  "write": [ "status" ],
  "null_base": false }

Target: this route reads (and, with a non-empty write allowlist, writes) a second tenant B’s PUBLIC subset — never the caller’s own tenant. The host resolves B from the first applicable via source and binds the target scope before the guest runs, confining every access to tenant = B AND <public subset>. Gated by the operator’s target_eligible_fields allowlist.

TenancySchema

The project-level tenant-isolation schema — the host-held facts the scope injector keys off, declared per project (not per component) with boatramp tenancy apply, not in SiteConfig. A target tenancy decision (above) needs the operator to have opened the axis in this schema; a project that declares none uses the legacy single-column scoping. Key fields:

compression

On-the-fly response compression. Opt-in, and complementary to serving a precompressed variant. A response is compressed only when it has no precompressed variant or existing Content-Encoding, its type is compressible, and (when the length is known) it is at least min_size. Credentialed responses are skipped for BREACH safety. See Compress responses.

gateway

Reverse-proxy gateway for publishing private services. None means no gateway routes. Declaring an upstream here is what authorizes reaching a private address — the SSRF guard stays public-only otherwise. Fields cover upstream pools, load balancing, and health checking; see Expose a private service through the gateway.