運用Run Kazari · Security

Run Kazari

Security

This document is the threat model and security reference for Kazari v1. It describes what Kazari protects, where the trust boundaries are, which limits apply, what an operator must do, and what the security reviews found.

Threat model#

Assets#

Actors#

• Anonymous visitor. Reads artifact pages. Can send any host header, path, query, method and header. Has no credential.
• Authenticated member. Holds an API key or OAuth token with some of artifacts:read, artifacts:write, artifacts:delete. May try to escape their scopes, act on other users’ artifacts beyond the write policy, exceed limits or quota, or attack the server with what they upload.
• Malicious bundle. Content uploaded by a member: HTML and JavaScript that runs in readers’ browsers, archives built to escape paths or exhaust resources, metadata built to inject headers.
• Malicious OAuth client. Anyone can register a client (DCR) or name a client ID metadata document URL. Such clients can send users through the authorization flow and make the server fetch URLs.
• Administrator. Trusted. Holds the admin token or an admin-scoped key.

Trust boundaries#

1. Browser to artifact host. Untrusted requests meet untrusted content. Everything served here is treated as hostile to everything else.
2. Browser or client to control plane. Every request must carry a bearer credential (or, for the OAuth pages, the consent cookie), and every action is authorised against scopes and the write policy.
3. Upload boundary. Bytes from members enter through inline JSON, multipart tar.gz or chunked staging. They are size-capped, path-validated and content-addressed before anything references them.
4. Kazari to the identity provider and to CIMD URLs. Outbound requests: OIDC tokens are verified cryptographically; metadata fetches are restricted to public addresses.
5. Reverse proxy to Kazari (proxy mode only). Kazari trusts the proxy’s X-Forwarded-For / X-Real-IP.

Origin isolation#

Every artifact is served from its own host, <slug>.<base>, and every pinned version from <slug>--v<N>.<base>. Each host is a separate web origin, so the browser’s same-origin policy keeps artifacts apart:

• Script in one artifact cannot read another artifact’s DOM, storage, cookies, IndexedDB or service workers, and cannot make credentialed same-origin requests to it.
• Artifacts cannot reach the control plane as same-origin. Control-plane credentials are bearer headers, never cookies, so a page cannot ride on a visitor’s session. The only cookie in the system is the OAuth consent cookie: __Host-kazari_oauth on mcp., path /, HttpOnly; Secure; SameSite=Lax, ten minutes. Kazari never sets a cookie with a Domain attribute, and the __Host- prefix makes browsers refuse one for that name from any other host.
• The site handler serves only GET and HEAD and never sets cookies. An artifact’s own script can still set cookies for its own host, and those are confined to that origin.

Origins are separate, but every artifact host and the control plane share one site (registrable domain), and cookies are scoped by site, not by origin:

• An artifact’s script can set a cookie with Domain=<base>, or with the parent domain of <base>, which the browser then sends to every host under it. Kazari’s only cookie cannot be planted that way (its __Host- prefix), and the consent form also checks Origin, but a page can still fill a visitor’s cookie jar for <base> past the 64 KiB header limit, after which every Kazari host answers that visitor 431 until they clear cookies.
• Requests from one artifact host to another, or to mcp.<base>, are same-site, so SameSite=Lax does not stop them.
• If <base> sits under a domain that serves other applications (for example art.example.com under example.com), artifact scripts can read that domain’s non-HttpOnly cookies set with Domain=example.com, and set cookies those applications will receive.

So give base_domain a registrable domain of its own (for example example-artifacts.com, not a subdomain of the company domain), and consider listing it on the Public Suffix List, which makes browsers treat each artifact host as its own site.

Arbitrary HTML and JavaScript is the product, so Kazari does not try to make uploaded content safe. It makes sure each artifact’s content can only harm its own origin.

Host handling (internal/site/host.go): the host is lower-cased and its port and trailing dot stripped. It must end in .<base> with exactly one label in front. The label splits on the last --v followed by digits (no leading zeros, at most nine digits), and the slug must pass the slug rules. Anything else, including the apex, deeper subdomains and IDNA labels (they contain --), gets the instance 404 page. Reserved slugs (api, mcp, admin, www, …) cannot be created, and the host router sends the control-plane hosts elsewhere before the site handler runs.

Path handling (internal/site/site.go): the decoded request path is refused (404) if it contains a control character, a backslash or a .. segment. That includes the percent-encoded forms, because the check runs after decoding. It is then cleaned and looked up in the version’s file map, which is built from validated paths only. No path is ever joined onto a filesystem path: blobs are opened by content hash. Directory redirects are always relative to the host (/<clean>/), so they cannot be turned into open redirects.

Header policy#

Every artifact response carries:

Control-plane hosts add Cross-Origin-Opener-Policy: same-origin, nosniff, Referrer-Policy: no-referrer and Cache-Control: no-store. The OAuth pages add X-Frame-Options: DENY and a CSP of default-src 'none'; style-src 'unsafe-inline'; form-action 'self' <redirect origin>. Raw file reads through the user API (GET /v1/artifacts/{slug}/files/...) are sent with Content-Security-Policy: default-src 'none'; sandbox, so artifact bytes can never run as a document on the api. origin.

Header values that come from users are restricted before they are stored. kazari.csp and per-file content types must be printable ASCII (no CR, LF, NUL, tabs or non-ASCII bytes). Content types must also parse as a media type and be at most 255 bytes.

Default CSP#

default-src 'self';
script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net https://unpkg.com;
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src 'self' https://fonts.gstatic.com;
img-src 'self' data: https:;
connect-src 'self';
frame-ancestors 'none'

The reasoning:

• Origin isolation is the main control, not the CSP. The CSP limits what an artifact can pull in and send out, not what it can do to itself.
• 'unsafe-inline' scripts and styles are allowed because generated artifacts are usually single-file HTML. The common public CDNs are allowed for the same reason.
• connect-src 'self' stops a page from sending data to a third party with fetch, XHR or WebSockets. This makes casual exfiltration of what a visitor types harder. It is not a hard guarantee: navigation and image beacons are still possible.
• frame-ancestors 'none' stops other sites from framing artifacts, which rules out clickjacking.
• allow_csp_override (on by default) lets an artifact replace the policy through kazari.csp. The override only affects that artifact’s own origin, so it can relax the artifact’s own protections but nobody else’s. Operators who want a fixed policy set it to false.

Upload trust boundary and limits#

Content enters through three paths, and all of them end in artifact.Service, which applies the same rules.

1. Inline JSON (POST/PUT /v1/artifacts, MCP tools): the body is capped with http.MaxBytesReader. UTF-8 or base64 file contents.
2. Multipart tar.gz: a manifest part (64 KiB cap) then a bundle part. The multipart stream is capped at MaxBodyBytes. The gzip and tar streams are decoded into one temporary spill file (never memory). Every decompressed byte of the tar stream counts against the same MaxBodyBytes: headers, PAX and GNU long-name records, padding, the data of skipped entries and file content, so a gzip bomb, a flood of empty entries or a stack of 1 MiB names stops at the cap. A kept name longer than 1024 bytes is refused as soon as it is read. Only regular files are kept: directories, symlinks, hard links, devices and FIFOs are skipped and never followed. Leading ./ is stripped, and absolute and .. names are rejected by path validation. The spill file is removed after the publish, and the hourly gc job removes any a crash left behind.
3. Chunked staging (/v1/uploads): an upload belongs to the user who began it; anyone else, and an expired upload, gets upload_not_found. Upload ids are 16 random bytes and are checked against their exact shape before they are used as a directory name, so they cannot escape the staging root. Staged files are stored under numeric names, never under their paths. Each chunk must start at the staged size; a retry of the last chunk is acknowledged. A chunk’s content type is checked like a manifest’s when the chunk arrives. The open-upload limit is checked in the transaction that creates the upload. Expired uploads and orphaned directories are swept.

Path rules (artifact.ValidatePath): non-empty; at most 1024 bytes; segments at most 255 bytes; relative; not a directory (no trailing /); no control characters, DEL, backslash or invalid UTF-8; cleaned with path.Clean; no .. left after cleaning. Paths are compared byte-for-byte: no case folding or Unicode normalisation, so a.html and A.html, or NFC and NFD forms, are different files. Duplicate paths in one request are rejected after cleaning.

Slug rules: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, 3 to 63 bytes, no --, not reserved, immutable after create.

Text fields: name and a version’s label at most 256 bytes, description at most 4096 bytes; valid UTF-8 with no C0 or C1 control characters, DEL or bidirectional override and isolate characters (description may hold newlines and tabs). They are returned by every listing and printed by the CLI, which also replaces control characters in what it prints.

Metadata: at most 64 pairs (configurable), keys ^[a-zA-Z0-9_.-]{1,64}$, values at most 4096 bytes. kazari.* keys are restricted to kazari.spa and kazari.indexable ("true"/"false") and kazari.csp (printable ASCII).

Authentication and authorisation#

API keys. Format kzk_<8-char prefix>_<52-char secret>, lower-case base32 from 40 + 256 random bits. Only the SHA-256 of the whole key is stored, and it is compared with crypto/subtle. The key is shown once at issue. Revoked and expired keys, and keys of disabled users, are refused. Disabling a user revokes all their keys. last_used_at is written at most once a minute.

Scopes. artifacts:read, artifacts:write, artifacts:delete, admin. Every user-API route needs its scope: reads read; create, update, publish, stale and uploads write; delete delete. A key or token’s scopes are capped at what the owner’s current role allows, so a demoted admin loses admin straight away. Admin power comes from the admin scope, not from the role alone: a principal is an admin only if the user has the admin role and the credential carries admin. An admin’s key issued as read-only stays read-only.

Admin host. /v1/ on admin. accepts the configured admin token (SHA-256 then constant-time compare, at least 32 characters) or a credential that resolves to an admin principal (admin role and admin scope). Everything else gets 401 or 403, and every attempt counts against the per-IP limit, so tokens cannot be guessed at speed. /health (which reports the version; the public /health on the apex does not) and /metrics are unauthenticated. With admin.listen set, the admin host is served only on that listener and the public listener answers admin.<base> with 404.

Write policy. auth.write_policy: shared (default) lets any member with artifacts:write change any artifact. "owner" limits changes to the owner and admins. Transfer is always owner- or admin-only. Listings show public artifacts plus the caller’s own; unlisted artifacts are hidden from other people’s listings but served to anyone who knows the URL. An unpublished (including hidden) or soft-deleted artifact is invisible to everyone but admins, its owner and the users who created or updated it: they alone can list it, get its record or read its files through the API or MCP. Changes are read-modify-write inside one transaction, so a concurrent update cannot undo a transfer, a delete or a visibility change, and blob garbage collection is locked out while a publish writes and commits its blobs.

OAuth 2.1 (mcp. host): public clients only; PKCE S256 required (43-char challenge, 43 to 128-char verifier, constant-time comparison). Redirect URIs must be https, or http on a loopback host. They are matched exactly, except that the port of a loopback URI is ignored (RFC 8252). resource must name this server’s MCP URL. Codes are single-use, consumed before they are checked, and live five minutes. Access tokens live one hour, refresh tokens thirty days, and all of them are stored hashed. Refresh tokens rotate; replay of a rotated token revokes its whole family. The authorization server offers and grants only the artifacts:* scopes: an OAuth token never carries admin, so approving a client never hands it the admin host. A grant approved with an API key (no identity provider) is bound to that key: it stops working when the key is revoked or expires or its user is disabled, and no token outlives the key. Disabling a user revokes their grants. The consent form must come from the consent page itself (Origin equal to the MCP origin, or Sec-Fetch-Site: same-origin), and its request id must equal the __Host- consent cookie, which no sibling host can set. Both matter because artifact pages are same-site with mcp. and run member-authored script. The upstream state and nonce are random per request and checked in constant time. An OAuth principal’s rate-limit and audit identity is its grant (oauth:<family>), the same across refreshes. Client ID metadata documents are fetched only from public unicast addresses: loopback, RFC 1918, link-local, CGNAT, NAT64/6to4, documentation, benchmarking and reserved ranges are refused at dial time, after DNS resolution, so DNS rebinding cannot get around the check.

OIDC relying party. ID tokens are verified against the provider’s JWKS, with issuer, audience (client id), expiry and nonce checks. The upstream code exchange uses PKCE. Email-based linking and provisioning only trust a verified email. For Google, a non-Gmail address counts as verified only when the hd claim equals its domain, so a consumer Google account registered on a company address (for example by someone who has since left) cannot sign in as that domain. For Entra ID, a missing email_verified counts as verified (single-tenant only; the multi-tenant common issuer is not supported).

Out of scope for v1#

• Public-instance hardening. v1 assumes the members are colleagues: any member can publish arbitrary HTML on the instance’s domain, and the domain will be used for phishing if strangers can sign up. Do not run an instance with open sign-up (auto_provision without allowed_domains). There is no malware scanning, abuse reporting flow or per-artifact takedown other than the admin hide endpoint.
• Gated visibility. public and unlisted are both served to anyone with the URL. There is no per-artifact access control on artifact hosts in v1. Do not publish secrets.
• Isolation between artifacts on the same instance beyond the browser’s origin model. For example, a CSP override that allows framing or third parties is the artifact owner’s choice.
• Protecting artifacts from admins. Admins can read, transfer and delete everything.
• Enterprise managed auth (RFC 7523 JWT bearer grant) is a Phase 4 item.

Operator checklist#

1. Keep the admin host on its own listener (admin.listen, for example 127.0.0.1:9443), or reach it only through a VPN. With admin.listen set, the public listener stops serving admin.<base>, including the unauthenticated /metrics and /health.
2. Rotate the admin token out. Use it to create the first admin user, issue that user a key with the admin scope, check that the key works on the admin host, then remove auth.admin_token / KAZARI_AUTH_ADMIN_TOKEN and restart. While it exists it must be at least 32 characters (openssl rand -hex 32). Pass secrets through the environment: ${NAME} references in the YAML file, values in kazari.env or .env.
3. Proxy mode. Turn on listen.proxy_mode only behind exactly one reverse proxy, and make sure nothing can reach Kazari’s plain-HTTP port except that proxy. Kazari takes the rightmost X-Forwarded-For entry, the one your proxy added, then X-Real-IP. A proxy that appends (nginx’s $proxy_add_x_forwarded_for) or overwrites (Caddy) both work. With two proxies in a chain (CDN, then proxy), the per-IP limit applies to the CDN’s address.
4. Identity provider. Set allowed_domains. Use auto_provision only with it. For Entra ID use a single-tenant app. Keep admin_emails short: people in it become admins on first sign-in.
5. Write policy. Choose owner if members should not be able to change each other’s artifacts.
6. CSP override. Set serve.allow_csp_override: false if you need the instance policy to hold for every artifact.
7. Backups. Back up data_dir: kazari.db (use SQLite’s online backup or stop the service) and blobs/. certmagic/ holds certificate keys, and the database holds key and token hashes and user emails, so treat backups as secrets. uploads/ is transient and does not need backing up.
8. Updates. Run the latest release. Releases are built with -trimpath and CGO_ENABLED=0, by workflows whose actions are pinned to commit SHAs, from base images pinned by digest.
9. Domain. Serve artifacts from a registrable domain of their own, not a subdomain of a domain your other applications use (see Origin isolation).

Reporting a vulnerability#

Please report vulnerabilities privately, not in a public issue. Use the repository’s private vulnerability reporting (the Security tab, then Report a vulnerability). Include the version (kazari version), the configuration that matters, and steps to reproduce. You should get an answer within a week. Please give us a reasonable window to ship a fix before you disclose.

Findings log (pre-v1.0 review, 2026-10-24)#

Scope: internal/site, artifact, httpapi, upload, auth, user, oauth, oidc, middleware. Every fix has a regression test.

Findings log (whole-repository review, 2026-10-24)#

Scope: everything, including what the first review left out (app, mcpserver, sqlite, blob, scheduler, metrics, certs, config, cli, present, the deploy files and the workflows). Every code fix has a regression test; the server timeouts are constants without one.