voussoir

The two origins

A page's origin is one of the few things a webview will not let you lie about, and Voussoir's policy is built on it. There are two spellings, and knowing which you are on explains three otherwise confusing behaviours.

Desktop

Pages are served from voussoir://localhost, a custom scheme the shell intercepts itself. window.location.origin is voussoir://localhost, and the security policy lists exactly that.

Windows

WebView2 cannot intercept a custom scheme. wry therefore rewrites voussoir://localhost to http://voussoir.localhost and intercepts that instead. Same handler, same document, different origin string.

This is the one place a cross-platform app can notice the platform in its own URLs. Two consequences:

Earlier versions used a http://localhost spelling on Windows, which collided with any local dev server and made the CSP ambiguous. The voussoir.localhost name is reserved for this purpose, so it cannot collide with a real host.

Android

WebResourceRequest carries no body, so the custom protocol cannot carry an invoke payload at all. Android uses wry's postMessage bridge instead, and Rust resolves the page's promise from the other side. The envelope, registry, allowlist and policy are shared; only the transport differs.

The consequence for app code is zero: a command behaves the same. The consequence for a page is that fetch("voussoir://localhost/__voussoir/…") is not the transport on Android, so call window.voussoir.invoke rather than reaching for the endpoint by hand.

iOS

WKURLSchemeHandler intercepts voussoir://localhost the way the desktop does, so the origin and the policy are the desktop ones. This is deliberate: it is the one mobile platform where the insecure-by-default http:// workaround is not needed.

What to write in a page

Relative URLs, and window.voussoir.invoke. Both work on every platform, and neither requires the page to know which origin it is on. When you cannot avoid an absolute URL, build it from voussoir.pageOrigin rather than from a literal; that member exists so the rewritten spelling stays an implementation detail instead of something every page has to know.

voussoir.pageOrigin arrived in shim protocol 3, so the honest feature test is voussoir.protocol >= 3 with a relative URL as the fallback.

Edit this page on GitHub