Features / Atomic publishing

Atomic publishing

Atomic publishing lets you, a CI job or an AI agent push a new version of a static site that is checked and signed before it goes live, switches over in one step, and can be rolled back with one command. This page covers the release model, the command-line flow, the ai-publish configuration block, the pre-flight checks and the network publishing endpoint.

What an atomic release is

Each publish creates a new release: a complete copy of the site written to its own directory in a release store, together with a release.json record (file count, size, SHA-256 hash of the file list, note, signature). A release is never modified after it is written.

A small pointer file names the active release. Publishing writes the new release in full, checks it, and only then moves the pointer, so visitors see either the old site or the new one, never a mix. Rolling back moves the pointer to an earlier release. The store keeps the newest keep-versions releases and deletes older ones, never the active one.

A running server notices a pointer change made by the command line on the next request it serves for that site, checking at most once per second, and verifies the release before switching to it.

Releases are signed with Ed25519, a public-key signature scheme: you keep the secret key wherever you build the site, and the server holds only the public key. A release that is not signed by the matching key is refused.

Smallest working setup

Create a key pair. The secret key file is written with mode 0600.

$ miraserve publish keygen --secret deploy.key --public deploy.pub
OK: generated Ed25519 publishing key pair (public: 'deploy.pub', secret: 'deploy.key')

Copy deploy.pub to the server (here /etc/miraserve/deploy.pub) and add an ai-publish block to the site. A site with ai-publish serves the active release; it does not need a root.

server {
    listen ":443" protocols="h3,h2,h1"
    tls {
        cert "/etc/miraserve/certs/example.com.crt"
        key "/etc/miraserve/certs/example.com.key"
    }
}

site "www.example.com" {
    ai-publish {
        storage "/var/lib/miraserve/releases/www"
        site-id "www-example"
        keep-versions 10
        require-signature "ed25519:/etc/miraserve/deploy.pub"
        preflight-checks "no-secrets" "no-inline-scripts" "csp-valid" "max-size=50MB"
    }
}

Deploy a directory. --config loads the site's real policy (signature key, checks, storage), so the command line enforces the same rules as the server. Run it as a user that can write to the store, such as miraserve on a systemd install.

$ miraserve publish deploy ./site --config /etc/miraserve/conf/miraserve.kdl --key deploy.key --note "first release"
OK: published release rel-1795106185-0001-88aea5de (2 file(s), 225 bytes, signed=true, sha256=88aea5de5f81774ef5b571a835dea4bfc574407c4f954bc902bba7ab5037d4a0)
$ miraserve publish deploy ./site --config /etc/miraserve/conf/miraserve.kdl --key deploy.key --note "second release"
OK: published release rel-1795106186-0001-2ca2783e (2 file(s), 164 bytes, signed=true, sha256=2ca2783e7313dfa8a685633af83b3bc2eab3805b2d9bdbd9aaaf9611130e03fd)

List releases; * marks the active one:

$ miraserve publish list --storage /var/lib/miraserve/releases/www
* rel-1795106186-0001-2ca2783e  files=2  bytes=164  signed=true  note=second release
  rel-1795106185-0001-88aea5de  files=2  bytes=225  signed=true  note=first release

Roll back to the previous release, or to a specific one with --release-id:

$ miraserve publish rollback --config /etc/miraserve/conf/miraserve.kdl
OK: rolled back active release to rel-1795106185-0001-88aea5de (sha256=88aea5de5f81774ef5b571a835dea4bfc574407c4f954bc902bba7ab5037d4a0)

If the config defines more than one ai-publish site, add --site with the host name or site-id.

A deploy without --key against a site with require-signature fails with error: bundle is missing required Ed25519 signature. A deploy without --config is refused unless you pass --allow-unconfigured-policy, which skips the site's policy and is meant only for local experiments.

Before your first publish

  • Set site-id before the first publish and do not change it afterwards. The site ID is written into every signed release and into the expected audience of publishing tokens. Without it, MiraServe uses the site's first host name, which changes if you reorder or add host names (check warns with W018 for multiple or wildcard hosts). Releases signed for one site ID are refused for another, so if you must change it, republish the site afterwards.
  • Always set require-signature, including when you use auth="oauth-jwt". Without it, anyone who can authenticate to the publishing endpoint can publish unsigned content; with it, they also need content signed by your deploy key.
  • List preflight-checks explicitly. If you omit the directive, only no-secrets and max-size=50MB run, and HTML and SVG files are not inspected at all.

Pre-flight checks

Every release is checked before it is written. If any check fails, nothing is written and the live site is unchanged. The command prints each violation:

$ miraserve publish deploy ./site --config /etc/miraserve/conf/miraserve.kdl --key deploy.key
error: pre-flight safety checks rejected bundle (1 violation(s))
  - [NO_INLINE_SCRIPTS] index.html: markup contains inline <script> block (external scripts with src= only)

Always applied

  • The release must contain at least one file.
  • File paths must be relative, without .., empty segments, backslashes, colons, control characters, trailing dots or spaces, or reserved Windows device names. Two paths that differ only in letter case are refused.
  • Dotfiles and dot-directories (.env, .git/) are refused, except .well-known.
  • Pre-compressed files (.gz, .br, .zst, .svgz and similar) are refused, because the server could serve them in place of the checked original.

Configurable checks

CheckWhat it doesWhat it does not do
no-secretsScans every file, including UTF-16 text, for PEM private key blocks, MiraServe signing keys, AWS access key IDs, and API keys with recognisable prefixes (Anthropic, OpenAI, Stripe live, GitHub, Slack, Google).It is a pattern match. It does not find passwords, database URLs, or keys without a known prefix.
no-inline-scriptsParses HTML, XHTML, SVG and other XML files and refuses inline <script> content (except valid JSON data blocks, import maps and speculation rules), on* event-handler attributes, javascript: and similar URLs, srcdoc, scripted SVG animation, and data: URLs on embedding elements. <script src="..."> with no inline content is allowed.It covers inline script in markup only. It does not stop a page from loading a separate .js file from the release or from another site, and it does not inspect JavaScript files. Set a Content-Security-Policy to control which scripts may run.
csp-validIf a page has a <meta http-equiv="Content-Security-Policy"> tag, refuses it when the policy contains 'unsafe-inline', 'unsafe-eval', javascript: or data:.It does not require a policy to exist and does not add one.
max-size=<size>Refuses releases larger in total than the size, for example 50MB.
max-files=<n>Refuses releases with more than n files.

When no-inline-scripts or csp-valid is enabled, markup files are parsed strictly, which has two practical effects:

  • HTML pages with parse errors are refused, for example a duplicate attribute or a mis-nested tag (<p><b>text</p>). A missing <!DOCTYPE html> is tolerated. Files must be UTF-8.
  • SVG and other XML files that contain a DOCTYPE are refused. Many drawing tools add one; remove the <!DOCTYPE ...> line from the SVG before publishing.

The ai-publish block

DirectiveDefaultMeaning
storagerequiredDirectory of the release store.
site-idthe site's first host nameStable identifier bound into signatures and token audiences. No whitespace or slashes, at most 255 characters.
keep-versions10Releases kept for rollback, 1 to 1000.
require-signaturenone"ed25519:/path/to/key.pub". Releases must be signed by the matching secret key.
preflight-checks"no-secrets" "max-size=50MB"Checks to run; see pre-flight checks. Setting the directive replaces the default list.
mcp-endpointnoneNetwork publishing endpoint: a path and auth="oauth-jwt", "mtls" or "ed25519". auth="none" is rejected.
jwt-public-keythe require-signature keyKey that verifies publishing tokens in oauth-jwt mode: "ed25519:/path" or "miraserve-ed25519-pub:<base64>". Only valid with auth="oauth-jwt".
jwt-issuernoneRequired iss claim. Only valid with auth="oauth-jwt".
allowed-subjectsnoneClient certificate subjects allowed in mtls mode, as a full DN or one component such as "CN=deploy-agent". Only valid with auth="mtls".

check requires either require-signature or an mcp-endpoint, and warns with W009 if no-secrets is missing. Configuration errors in this block are reported as E401 (and E402 for a malformed check).

Publishing over the network

MCP (the Model Context Protocol) is a protocol that lets AI agents discover and call tools on a server; its messages use JSON-RPC, a simple request and response format in JSON. With mcp-endpoint, MiraServe serves an MCP endpoint at that path on the site, so an agent or a CI job can publish without shell access. The endpoint accepts HTTPS only and offers four tools: site_publish, site_rollback, site_list_releases and site_status. Every request is authenticated, and every published release still goes through signature verification and pre-flight checks.

auth="oauth-jwt"

site "www.example.com" {
    ai-publish {
        storage "/var/lib/miraserve/releases/www"
        site-id "www-example"
        require-signature "ed25519:/etc/miraserve/deploy.pub"
        jwt-public-key "ed25519:/etc/miraserve/publish-jwt.pub"
        jwt-issuer "https://auth.example.com"
        preflight-checks "no-secrets" "no-inline-scripts" "csp-valid" "max-size=50MB"
        mcp-endpoint "/_miraserve/publish" auth="oauth-jwt"
    }
}

Callers send Authorization: Bearer <token>. The token must be a JWT (a signed JSON token) using the EdDSA algorithm, verified with jwt-public-key. It needs a non-empty sub, an exp, an aud equal to the site-id, an iss equal to jwt-issuer when set, and a lifetime of at most 900 seconds. A scope (space-separated) or scp (list) claim is required and decides which tools are allowed:

ScopeTools
publish:readsite_list_releases, site_status
publish:rollbackthe above and site_rollback
publish:writethe above and site_publish
publish or publish:adminall tools

Use a separate key for tokens (jwt-public-key) and still set require-signature, so a leaked token alone cannot publish content.

auth="mtls"

Callers present a client certificate (mutual TLS) issued by the client-ca configured on the site or server. This mode also requires require-signature. Set allowed-subjects, otherwise any certificate from that CA can list releases and roll back (check warns with W019).

site "www.example.com" {
    tls {
        client-ca "/etc/miraserve/certs/deploy-ca.pem"
    }

    ai-publish {
        storage "/var/lib/miraserve/releases/www"
        site-id "www-example"
        require-signature "ed25519:/etc/miraserve/deploy.pub"
        allowed-subjects "CN=deploy-agent"
        mcp-endpoint "/_miraserve/publish" auth="mtls"
    }
}

auth="ed25519"

Each request is signed with the deploy key itself, and require-signature is required. The caller sends X-MiraServe-Timestamp (Unix seconds, within 300 seconds of the server clock), optionally X-MiraServe-Nonce, and X-MiraServe-Signature: a base64 Ed25519 signature over these lines joined by newlines:

POST
<site-id, lower case>
<endpoint path>
<timestamp>
<nonce, or empty>
<hex SHA-256 of the request body>

A signed request can be used only once.

Signing and verifying bundles separately

publish sign packs a directory into a signed JSON bundle, and publish verify checks one. They are useful when signing happens on a different machine from the deploy.

$ miraserve publish sign ./site --key deploy.key --site-id www-example --note "built in CI" -o bundle.json
OK: signed 2 file(s) (manifest sha256: 47ffdaa0f462a24583a8b22722ad657bfd291770245d49ffa88264f24a5192a9) -> 'bundle.json'
$ miraserve publish verify --pubkey deploy.pub bundle.json
OK: valid Ed25519 signature (files: 2, manifest sha256: 47ffdaa0f462a24583a8b22722ad657bfd291770245d49ffa88264f24a5192a9)

Rotating the deploy key

When a site starts up or rolls back, stored releases are verified against the current public key. To change keys without losing rollback history, re-sign the stored releases with the new key, then point require-signature at the new public key and reload:

$ miraserve publish keygen --secret deploy2.key --public deploy2.pub
$ miraserve publish resign --config /etc/miraserve/conf/miraserve.kdl \
    --old-pubkey deploy.pub --key deploy2.key --pubkey deploy2.pub
OK: re-signed release rel-1795106186-0001-2ca2783e (sha256=2ca2783e7313dfa8a685633af83b3bc2eab3805b2d9bdbd9aaaf9611130e03fd)
OK: re-signed release rel-1795106185-0001-88aea5de (sha256=88aea5de5f81774ef5b571a835dea4bfc574407c4f954bc902bba7ab5037d4a0)

resign checks each release's stored hash, and with --old-pubkey its existing signature, before signing it again. Releases that were stored unsigned are not re-signed unless you pass --include-unsigned.

Command reference

CommandMain flags
publish keygen--secret (default publisher.key), --public (default publisher.pub), --force
publish deploy <dir>--config, --site, --key, --pubkey, --note, --storage, --no-inline-scripts, --allow-timestamp-reset, --allow-unconfigured-policy, --keep-versions (only with the previous flag), --format text|json
publish list--storage (required), --format
publish rollback--config, --site, --storage, --release-id, --pubkey, --format
publish sign <dir>--key, -o/--output (both required), --site-id, --note, --force
publish verify <bundle>--pubkey (required)
publish resign--key (required), --config, --site, --storage, --pubkey, --old-pubkey, --include-unsigned, --release-id, --format

Each release must be newer than the last one published to the store. If a host clock ran ahead and blocks later deploys, --allow-timestamp-reset on a command-line deploy recovers.

Limits

  • Publishing serves static files only. There is no build step and no server-side code.
  • The pre-flight checks reduce common mistakes; they are not a full security review of the content. In particular, scripts in separate files are not checked, so pair publishing with a Content-Security-Policy.
  • The repository does not include a client for the network endpoint; agents call its tools over standard MCP.