# Cloudhal threat model (alpha) Cloudhal lets AI agents change websites. The central security promise: **an agent can only do what its scopes allow, every change is recorded and reversible, and nothing goes live without a person.** This page lists who can do what, the controls behind each promise, and the risks we accept for the alpha. Report vulnerabilities as described in [SECURITY.md](../../SECURITY.md). ## Principals Staff roles are named sets of scopes (RFC-0005, ADR-0018). A person's role is read from their single membership on every request; without one they have no scopes. | Principal | How it authenticates | Can do | |---|---|---| | Owner | Better Auth session cookie (Studio) | Everything (`*`), including transferring ownership; exactly one per deployment | | Administrator | Session cookie | Every non-wildcard scope: content, structure, publish, rollback, site settings and domains, members (non-Owner), invites up to Administrator, others' agent keys (revoke, end elevations) | | Editor | Session cookie | Content, pages, taxonomies, redirects, publish, rollback, all Activity; invites Contributors and Authors | | Author | Session cookie | Own articles in any status; publishes own-only change sets (anything wider becomes a request an Editor decides) | | Contributor | Session cookie | Own never-published drafts (draft/review); proposes tags; never publishes | | Agent | API key (`x-api-key` or `Authorization: Bearer`) with explicit scopes | MCP tools only, within its scopes narrowed to its creator's current role; publish/rollback/delete wait for a person | | Local developer's agent | `cloudhal mcp` over stdio | All scopes on the local project; gated tools ask in the MCP client | | Automation key | API key (`x-api-key` or `Authorization: Bearer`) minted for one automation by the person who created it (RFC-0008) | An agent key that works only inside its automation's run windows (outside them only `begin_run`, `get_mode` and `pause_automation` answer); narrowed to its owner's current role, capped by the automation's mode cap, never `bypass`; within budgets; read, label and hide only once its run reads visitor-supplied text | | Scheduler | System actor (`sys_scheduler`) inside the admin Worker or the Node process; no credential | Publishes releases on behalf of the person who approved them, runs built-in jobs, opens and closes run windows (RFC-0008) | | Operator | Deployment token (bearer) | Export/import whole sites (`cloudhal push/pull`); recover ownership (`cloudhal owner transfer`); export/import reader comments, with commenters' emails (`cloudhal comments export|import --remote`, RFC-0007); read the scheduler's status and run a tick (`cloudhal schedules status|list|run-due --remote`, RFC-0008) | | Site visitor | — | Published pages; drafts only with a signed preview link; sends analytics beacons, which count only for published pages (RFC-0006); sends comments and reports, which are held for moderation (RFC-0007) | ## Promises and controls 1. **Agents stay inside their scopes, and an agent never exceeds the person whose key it uses.** Agent principals are refused on the REST API (403 everywhere except `/api/me`); MCP calls pass the policy engine (scopes × tool annotations × declared skill). A key's scopes must fit its creator's role when it is minted, and on every call they are narrowed to the creator's *current* role; a key whose creator is no longer a member is refused (401). Key modes and elevations are capped by the role (Contributor: `edits`); only the key's creator grants an elevation. Person-only scopes (`site:settings`, `members:*`, `agents:manage`, `audit:read`, `automations:manage`) never sit on a key. Keys cannot mint keys; permissions are server-only, and Better Auth's own `/api/auth/api-key/*`, `/api/auth/organization/*` and `/api/auth/admin/*` endpoints answer 404. Per-key rate limit 600/min. 2. **Nothing goes live without a person, unless the owner chose otherwise.** Publish, rollback and delete create a pending approval that a signed-in person decides in Studio (ADR-0014). The only exception is a key the owner put in `auto` mode, permanently or for a bounded time (5 min to 24 h, ADR-0016): it may publish article-only changes (nothing removed, at most 20) without a person (ADR-0015). Rollback and delete always wait. Modes are owner-only, never grant scopes, `bypass` is local only, and an elevation ends by itself because the mode is computed on every call. An agent may *ask* for an elevation (`request_elevation`), but only a signed-in owner of its key can grant it, for at most the time asked. Approvals are single-use and bound to the tool, exact arguments, the requesting agent and the content state; any change after the question voids them. Agents never receive a redeemable token. Scheduled publishes are approved by a person (or by an `auto`-mode key within its elevation window and 24 hours) against the exact pinned versions, re-checked when they run, executed at most once and never early; content scheduled for later is locked against edits and held back from ordinary publishes (RFC-0008). 3. **Every change is recorded and reversible.** Each MCP mutation snapshots the site; every tool call and decision is written to the audit log; rollback moves the published pointer to an ancestor snapshot. 4. **Agent-written content cannot run code. The only client scripts a site runs are Cloudhal's first-party scripts under `/_cloudhal/` (hashed, self-hosted, each switchable off): the analytics script; on pages with an open comment form, the comments module and its proof-of-work worker; on pages showing a video, the click-to-load player; and on pages with a live generative UI surface, the interaction runtime (RFC-0020 §4). The CSP allows no inline or third-party scripts; the one exception is Cloudflare Turnstile on comment pages, when the owner turns it on.** Agents write markdown only (no HTML sections, no edits to HTML bodies); markdown escapes raw HTML; links and image sources are limited to safe schemes. Site HTML on Cloudflare carries `script-src 'self'; connect-src 'self'; form-action 'self'` and `Referrer-Policy: strict-origin-when-cross-origin` (`cloudhal dev` and Node serve no CSP; see the accepted risks). The analytics script (`/_cloudhal/p..js`, ≤ 1 KB gzipped, plus the sampled vitals module `/_cloudhal/v..js` with `web-vitals`) is bundled at build time, served as an immutable static asset from the site's own origin and loads nothing from a third party. It is injected only into published `200` HTML while the site's setting is on, never into previews, errors or feeds (RFC-0006 §5.1). The comments module (`/_cloudhal/c..js`, ≈ 2 KB gzipped, budget 4 KB) and its worker (`/_cloudhal/cw..js`, ≈ 0.8 KB, pure-JS SHA-256, no WebAssembly) are built the same way, referenced only by pages whose thread is open, and store nothing on the device (no cookie, no `localStorage`). With Turnstile on, such a page carries its own policy adding `https://challenges.cloudflare.com` to `script-src` and `frame-src`; every other page keeps the default (RFC-0007 §7.6). `comments.available: false` in `cloudhal.json` removes the module and its endpoints from the deployment. The interaction runtime (`/_cloudhal/surface..js`, a constant module of ≈ 6 KB, ≈ 2 KB gzipped, versioned and hash-pinned by a test) is referenced only by surfaces with inputs or button actions. It reads the surface's data from an inert `