Oleg Isonen
df7ed327ab
Authentication and custom response headers use the same route-rule syntax, but the shared matcher and validator had auth-specific names. Give those functions generic names in `wsauth` and update the Builder header UI and SDK response-header schema to call them directly. All basic-auth logic remains in `wsauth`; this change adds no package or re-export. The project-build page matcher is different: it uses `URLPattern` and returns decoded parameters. Rename it to `matchUrlPattern` and document the behavior difference. For example, `/docs/*` matches `/docs` for authentication and headers, but not for the page matcher. Tests cover both behaviors. This renames the two public `wsauth` route exports. Published workers pinned to the older package retain the old API; the SaaS worker can adopt the new names after this package is released. Validation: `wsauth` tests, including its packaged consumer test; SDK page and response-header tests; project-build route and redirect tests; SDK, `wsauth`, project-build, and Builder typechecks.
@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:
- 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",
},
});