It owns shared authentication types, validators, route matching, build-time resource generation, and runtime enforcement helpers used by Builder-generated sites. The package is structured around auth methods so Webstudio can add methods beyond Basic Auth without changing the route auth model.

The first implemented method is HTTP Basic Auth.

Auth Config

Webstudio sync writes route authentication config at:

.webstudio/auth.json

Version 1 uses JSON with route strings as keys:

{
  "version": 1,
  "routes": {
    "/my/page": {
      "method": "basic",
      "login": "me",
      "password": "idiot"
    },
    "/bla/*": {
      "method": "basic",
      "login": "bla",
      "password": "blubb"
    }
  }
}

Routes use Webstudio's path pattern syntax. The guide covers validation, matching, and the differences between page paths and project rules. Authentication keeps the first matching rule when several rules cover one URL.

Basic Auth

Version 1 supports Basic Auth:

{
  "method": "basic",
  "login": "admin",
  "password": "secret"
}

Rules:

Login is required.
Password is required.
Login must not contain :.
Login must not contain whitespace.
Password must not contain whitespace.
Password may contain :.

The colon rule follows HTTP Basic Auth's user-id ":" password credential structure from RFC 7617.

Build Semantics

Build tools generate .webstudio/auth.json from Webstudio project data. The file is treated as build output and is overwritten on sync.

Generated auth sources are applied in this order:

Project-level auth config from Webstudio project settings
Page-level auth generated by Webstudio page settings

If both sources define the same route, the later source wins. Because routes are JSON object keys, the generated config file cannot represent duplicate routes.

Runtime

At runtime, protected requests without valid credentials receive:

new Response("Authentication required", {
  status: 401,
  headers: {
    "WWW-Authenticate": 'Basic realm="Webstudio"',
    "Cache-Control": "private, no-store",
  },
});