webstudio/packages/wsauth

@webstudio-is/wsauth

wsauth is Webstudio's generic authentication package.

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 the same path pattern syntax Webstudio uses for pages:

• Static segment: /about
• Named parameter: /blog/:slug
• Optional named parameter: /blog/:slug?
• Wildcard: /docs/*
• Named wildcard: /docs/:path*

Route rules:

• A route must start with /.
• A route must not contain repeating /.
• A route must not end with /, except the root route /.
• * and :name* wildcard segments must be the final segment.
• Named parameters use :name, :name?, or :name*.
• Parameter names must contain word characters only, matching \w+.

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:

1. Project-level auth config from Webstudio project settings
2. 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",
  },
});