Skip to content

Security Model

Astronaut CMS runs its repository session on the server. The admin panel is an untrusted user interface: it holds no token, speaks to no Git provider, and can ask your deployment for exactly the operations the CMS offers and nothing wider. Everything below follows from that.

The session cookie decides who is asking. It is an encrypted JWT (a JWE, dir + A256GCM), marked HttpOnly, SameSite=Lax and Secure on every host but loopback, whatever scheme a proxy forwards, and scoped to the CMS API path, so it is never attached to a request for your site’s own pages. The provider token lives inside it and is only ever decrypted inside a server route.

The operation registry decides what asking can accomplish. Every operation names a CMS capability — an entry in a collection, a file in the library — and none of them takes a repository path, a ref, a commit or a provider parameter. So a browser that has been fully compromised can still only do the things an editor could have done through the interface.

That second boundary is the one that matters most. Successful script injection in the admin can act as the editor while the tab is open, which is unavoidable for any cookie-authenticated application, but it has nothing portable to steal and no way to reach past the CMS into the repository.

The whole flow runs on the server. The browser is redirected out, redirected back, and handed a sealed cookie; it never sees an authorization code, a client secret, or the token the exchange produces.

Authorization Code with PKCE, at both providers. PKCE is not standing in for a client secret here, because the CMS is a confidential client and both GitHub and GitLab still require the secret at the token exchange. It is there because it binds a code to the browser that asked for it, which is the one thing a confidential client gets no other way. The verifier is minted per sign-in, kept in a short-lived sealed HttpOnly cookie rather than in sessionStorage where script could read it or plant one, and torn up by the callback however it ends, so exactly one code can ever be redeemed against it.

That binding is also the whole of the callback’s CSRF defence, which is why there is no separate state secret to keep in step with it. state carries the challenge instead, so a callback that does not match the sign-in cookie is refused after one SHA-256 and before any authorization code is spent at the provider.

Cookie authentication is ambient: the browser attaches the cookie to any request to your origin, whoever caused it. SameSite=Lax already blocks a cross-site POST, and every mutating CMS request is additionally checked against Sec-Fetch-Site (falling back to Origin), so the rule is enforced where it is stated rather than assumed from a cookie attribute.

Encryption, not signing. A signed JWT is base64, readable by anyone holding it, which would be the wrong choice for a cookie carrying a provider access token. This is a JWE: the same AES-GCM the CMS used before, inside a standard envelope.

The envelope buys two things a hand-rolled seal has to be talked into:

  • exp the server enforces. A cookie’s Max-Age is the browser’s to honour. The token carries its own expiry, so a copied value stops working regardless.
  • aud binding. Every kind of token the CMS issues shares one key. Without an audience, a session would verify as a sign-in cookie — and, once MCP lands, an authorization code as an access token. Binding it makes that structural rather than a matter of which fields each reader happens to check.

It is also what MCP’s authorization codes and access tokens will be issued as, so there is one token mechanism rather than two.

There is no session secret to generate. The key is derived from the OAuth client secret your deployment already holds — high entropy, server-only, identical on every instance, and stable across deploys, which is exactly what a cookie key has to be.

The derivation is HKDF-SHA256 with a fixed info string, so the two are separate keys that happen to share one input: the cookie key reveals nothing about the client secret, and a secret used for anything else derives a different key. Reusing it costs nothing in strength, because anyone holding the client secret can already impersonate your OAuth app at the provider, which is strictly worse than forging a session.

Set ASTRONAUT_CMS_SESSION_SECRET to key sessions off something else instead — to expire every session without touching your OAuth app, or to share one session across several services.

The session is stateless, so a serverless deployment needs no database and no sticky instance. The cost is that the cookie itself cannot be torn up before it expires. What it grants can be, though.

A call that carries the editor’s own token is re-decided by the provider every time, so a collaborator removed from the repository fails it immediately. Two things in the CMS do not work that way: the assistant relay and an object-store media library both spend the deployment’s own credentials, and neither asks the provider anything. So the server re-checks repository access before it serves any request, and records the confirmation in the session cookie so it stands for five minutes. It lives in the cookie rather than in memory because a serverless deployment answers most requests from an instance that has never seen this editor before, and an in-memory window would mean an outbound round trip on the critical path of nearly every request. Removing someone’s access therefore stops them spending your AI budget and rewriting your bucket within that window, not in thirty days.

Signing out is not only local either. The CMS revokes the token at the provider as well, so the grant ends when the editor says so rather than whenever it would have lapsed on its own; both providers revoke the grant rather than the single credential, so the refresh token goes with it. It is best effort, because the cookie is cleared whatever the provider answers, and it is deliberately the one thing a session the CMS has otherwise stopped honouring can still do.

Rotating the OAuth client secret invalidates every session at once, which is the thing you would do on compromise anyway. That is the immediate lever, and the five-minute re-check is the one that follows a routine offboarding.

Everything an anonymous request can reach, and what it costs:

Request Answer Work done
GET /admin A shell, a stylesheet and a ~1 kB bootstrap None: the page reads no cookie
GET /_astronaut-cms/api/session Where to sign in, and no config Read one cookie header
GET /login Redirect to the provider One token encrypt
GET /callback Redirect back One SHA-256, then an outbound call to the provider only if the callback matches the sign-in cookie
Anything else 401 Not signed in. Read one cookie header

The admin page is the part worth dwelling on. It is a static shell that reads no session at all, which is what keeps the cookie off your site’s own traffic: a page that had to read the cookie would need it scoped wide enough to reach that page.

What the shell loads is a bootstrap that asks the session endpoint who is asking. Your deployment’s configuration, the inventory of bucket origin, preview URL and model list, is part of that endpoint’s answer and only for a recognised editor. It used to be compiled into the admin bundle, where anyone who knew the chunk’s URL could read it.

Be precise about what the rest of that split buys, because it is less than it looks. The admin bundle sits behind a dynamic import, so an anonymous visitor does not download it, but a dynamic import is not an access check. The chunk is a static asset your host serves to whoever asks for it by name, and the collection manifest inside it, which describes every collection’s fields and file layout, is still compiled in. So treat the bundle as public and the config as private, and if the manifest is sensitive for your site, put an access proxy in front of /admin.

One piece of configuration the shell cannot hold back either. A content security policy has to be in place before any script runs, so if your media library uploads straight to an object store, that store’s origin is named in the page’s connect-src to anyone who loads it. It says where the store lives and nothing about what is in it.

A request with no session cookie does no cryptography and reads no environment variable before its 401, and a request with a forged one is answered identically to one with none. A deployment that cannot reach its own secret reports that through the session endpoint, so it reaches the sign-in screen where an operator looks, rather than whoever sends a cookie.

Moving the work server-side moved the cost with it: what an editor’s browser used to spend is now your compute and your provider quota. Three budgets bound it, and all three are in-process.

Surface Budget What it stops
Sign-in (/login, /callback) 20/min, 4 at once, per caller address An unauthenticated flood of code exchanges, each an outbound request to the provider
Everything else (/rpc) 300 operations/min, 12 requests at once, per editor A runaway assistant loop or a compromised tab
The reference scan 10/min, 1 at once, per editor The one operation that reads every entry in the repository

The sign-in cap matters more than its size suggests. Redeeming a code means calling the provider, so a flood costs invocations and risks the provider rate-limiting your deployment’s address, which would break sign-in for everyone. PKCE narrows what can reach that call at all: a callback is checked against the sign-in cookie first, so only a caller who started a real sign-in gets as far as spending one.

The admin sends whatever it needs in the same tick as one request, so a navigation is one invocation rather than five. The budget is charged per operation rather than per request, and a batch is capped at twenty, so batching spends fewer invocations on the same budget instead of working around it.

The one amplification left is reading an entry whose format the caller did not name: the server tries each extension the collection allows, so up to four provider requests for one call. It is bounded and charged to the editor’s own provider quota rather than to a shared one.

Every write carries the version of the file it was based on — saving, deleting, renaming and reordering alike — so a write cannot silently discard one that landed while the editor was open. The version is opaque — the server compares it, never dereferences it — so it stays a token the caller echoes back rather than the repository ref the operation registry exists to keep out of a caller’s hands.

Each backend lowers it to a precondition the provider enforces: last_commit_id on GitLab’s commit API, a blob-hash check against the very commit the write will name as its parent on GitHub (where the branch is then advanced without force, so a branch that moved in between fails as a non-fast-forward), and a content digest against the working tree in development. A mismatch is a 412, kept distinct from the 409 a provider returns when it cannot merge a branch: both are the editor’s to resolve, but only one of them is resolved by reloading the entry.

For a file collection the version is the container’s, so editing one entry conflicts with a concurrent edit to any other. That is correct rather than strict: they are the same file, and the save rewrites all of them. Reordering carries that same container version.

Renaming is two writes, of which only the first is based on what the caller read — the second is based on what the request has just done. Which one that is depends on the layout: in a file collection both entries share a container, so the version guards the write that adds the new entry; in a glob collection they are separate files, so it guards the removal of the old one.

The assistant’s partial-edit tools carry the version of the read they derived the edit from, so a human saving the same entry mid-run refuses the agent’s write rather than losing their own. A full overwrite carries none, because there is nothing it was based on — that tool is documented as replacing whatever is there. Duplicating carries none either: the copy lands at an id nothing has read, so there is no version a caller could honestly name, and what a duplicate has to be safe against is an occupied destination, which the backend checks.

Signing in proves write access to the configured repository. The Git provider knows nothing about your bucket or your AI gateway, so that same session is also what entitles a caller to administer the media library and to spend the shared AI gateway credential.

Anyone you trust to push to the repository is trusted with all of it. If those need to be separate grants, the repository is the wrong place to express that.

Content Security Policy and response headers

Section titled “Content Security Policy and response headers”

Because the admin holds no credential and makes no cross-origin call, its policy is short:

default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline';
img-src 'self' data: blob: https:; font-src 'self' data:; connect-src 'self';
worker-src blob:; frame-src 'none'; frame-ancestors 'none';
base-uri 'none'; form-action 'self'

script-src 'self' with no inline scripts is what carries the weight: it keeps injected markup from becoming script in the first place. connect-src 'self' means a script that did get in has nowhere to send anything. The one exception is a presigned media upload, whose store origin is added, because those bytes go browser-to-store.

The CMS needs an SSR adapter, so the admin always renders on demand and the policy always reaches the browser as a header — which is what lets it carry frame-ancestors, something a <meta> policy cannot. Every CMS response also carries X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Cross-Origin-Resource-Policy: same-origin and Cross-Origin-Opener-Policy: same-origin. Media served through the CMS adds Content-Security-Policy: sandbox and keeps its own type only for images, videos and audio, everything else is application/octet-stream, so no library file can run as a page or load as a script on the admin’s origin.

worker-src blob: admits only workers started from a blob, because a blob worker inherits this policy. A worker loaded from a URL would run under the headers of its own response, which a site’s static assets usually lack.

The CMS ships its code in two halves that treat their dependencies differently.

The server half, meaning the API, the storage backends and the integration, compiles in no third-party code. Its libraries are regular dependencies of the package, so a fix reaches your site through npm update, Renovate or Dependabot without waiting for a release, and npm audit sees them.

The admin half is one prebuilt bundle, so your site installs none of its several hundred packages, the editor and its toolchain among them. None of that code ever runs on the server. The package’s build enforces this: a server import of any package that is not a declared dependency fails it.

A flaw in a bundled package can therefore reach at most an editor’s browser tab, where it meets the rest of this page. The policy above keeps injected markup from becoming script and gives a script that got in nowhere to send anything. The session cookie is HttpOnly, every write is validated on the server, and publishing needs a human.

Attached documents are the one place the admin parses bytes from outside the repository. A PDF or Word file is read in a worker of its own that has no DOM and no admin state, runs under the admin’s policy and is terminated after that one file.

The licenses of the bundled packages ship in the package as THIRD_PARTY_LICENSES.md in dist/admin for the scripts and in dist/styles for the stylesheet and its fonts. A deployment that serves the admin also distributes that code, so wherever the admin runs, both are served at /_astronaut-cms/THIRD_PARTY_LICENSES.txt, which its header links to. Your site’s own bundled dependencies remain yours to credit.

The bytes go straight from the browser to the store, and the server’s decisions ride along in the signature rather than running beside it.

  1. The browser asks where to put the bytes

    The server checks the path, the extension and the size, then signs a URL for that key, that byte count and that content type. The type comes from the file extension, never from the uploader: a store serves back whatever type it was given, so choosing the type is choosing how the bytes are interpreted. Unless the editor explicitly chose to replace a file, an If-None-Match: * precondition is signed in too.

  2. The browser uploads directly to the store

    The bytes never pass through a serverless function, which is what keeps large files working across hosts with small request-body limits. Every term is part of the signature, so the URL is usable for that file at that key and nothing else: an understated size, a different content type or an occupied destination is refused by the store as the write happens.

Active types (SVG and friends) get Content-Disposition: attachment signed in as well, so the store serves them as downloads rather than as pages.

An object-store library never sends its bytes through the CMS server. It is addressed at its public base directly, so a page of thumbnails costs no function invocations and leaks nothing the base does not already serve. A bucket that must stay closed sits behind a CDN holding the credential, which is the public base as far as the CMS is concerned, and the credential never leaves the server or the CDN.

Every library URL carries the file’s version, whichever way it is served, and it always means the same thing: this address is these bytes. On a public base that is what stops a CDN from serving a replaced file to every editor until it expires. Through the CMS it is what lets the answer be cached indefinitely — but only when the version matches what the backend just read back. The policy comes from the file rather than from whatever a caller appended, so a ?v the file does not have gets the short cache rather than pinning the wrong bytes in a browser for a year.

That version is also the response’s ETag, so the short cache ends in a 304 with no body rather than in the file again. A backend that cannot name its bytes gets the short cache and no entity tag, which is the honest answer rather than a wrong one.

A redirect cannot carry the long cache, because where it points is the provider’s to expire. So where a backend would rather redirect and the caller named a version — a GitHub repository library, whose contents API hands out a short-lived download URL — the bytes are served from the CMS instead. That is the only way the address can mean what it says, and it is the cheaper answer too: the browser keeps that version for good rather than coming back for a fresh redirect every few minutes. A request that names no version still redirects.

The bucket does not have to be public for the first case: a CDN holding the credential (CloudFront with an origin access control, an R2 custom domain) is a public base as far as the CMS is concerned, and is the setup to prefer. See Reading the library.

Deletion and renaming are refused while referenced

Section titled “Deletion and renaming are refused while referenced”

The server reads every entry and refuses to remove or move a file that content still points at. This is a rule of the library rather than caller discipline: the assistant cannot talk its way past it, because only a human who has been shown those references in the media view can acknowledge them and proceed.

Beyond that, deletion is undoable: the object is moved to a .trash/ prefix inside the library rather than dropped, and the media view restores it from there. This is what makes it safe to let the assistant delete media at all, since a wrong delete costs a restore rather than the file. Restoring and purging are the media view’s alone, so the assistant cannot undo its own deletion, nor make one permanent.

Uploaded files are attacker-influenced bytes your site serves back, and some allowed types are documents a browser will run. media.publicUrl must therefore not share an origin with the site itself; the integration refuses the configuration when your astro.config declares a site it can check against.

Serve the bucket from a dedicated host (a CDN subdomain), without cookies, and with X-Content-Type-Options: nosniff on its responses.

The agent reads content: entry bodies, attached documents, media listings. Any of it can try to instruct the model, so the boundary is not “will the model be fooled” but “what is the worst a fooled model can do”.

Every tool the agent can call is one operation on the CMS server, validated exactly as the interface’s own calls are. Repository writes land in the pending changeset — the draft branch the editor reviews and then publishes or discards as a whole — so a destructive call talked out of a model costs a discard. A branch preview builds that changeset before anyone reviews it, and the published site serves it to every visitor, so an entry body may carry no code. See allowed body content for the subset every write is held to. Media deletion and renaming are refused while content still references the file, and an object-store deletion goes to the trash prefix. The agent cannot publish.

The relay holds the gateway credential, so a session is otherwise a licence to bill your account without bound. Request size and output tokens are capped per editor by ai.limits; request rate and concurrency are capped too, but follow from ai.maxSteps rather than being configured beside it.

  1. Register a GitHub App, not an OAuth App

    Install it only on the repository the CMS edits, grant Contents + Pull requests, and enable expiring user tokens.

  2. Serve media from a separate origin

    A CDN subdomain, cookieless, with nosniff.

  3. Keep dependencies updated

    Let Renovate or Dependabot update your lockfile, which covers the CMS’s server dependencies too.

  4. Cap AI spend at the gateway

    ai.limits is the brake; the gateway budget is the ceiling.

  5. Set a lifecycle rule on the media .trash/ prefix

    Long enough to undo a mistake, short enough not to keep deleted files forever.

  6. Enable bucket versioning

    Recoverable deletion is in the CMS; versioning is what survives a credential compromise.