Charter
The charter is the capability policy of a window's own document. It says what the renderer may reach in the kernel, and the kernel refuses everything else. It plays the role Electron gives to a hand-written preload (but enforced by the runtime, not by convention) and the role Tauri gives to a capabilities file (but declared in TypeScript, applied per window and revocable).
import { app, BrowserWindow, charterPresets, onCharterDenied } from '@owear/core'
app.whenReady().then(() => {
const win = new BrowserWindow({
charter: { allow: ['ow-window', 'theme', 'fs:readText'] },
})
})
Once a window has a charter, everything it does not grant is refused. No charter means no filtering, so this is opt-in per window and cannot break an app that does not use it.
Declaring
type CharterEntry = string // 'fs' | 'fs:readText' | 'fs:*' | '*'
interface Charter {
allow?: CharterEntry | CharterEntry[]
deny?: CharterEntry | CharterEntry[]
enforce?: boolean // default: true when any rule is declared
}
allow— the capabilities the window may use.deny— explicit refusals.denyalways wins overallow, so you can grant a whole module and carve out single functions.enforce: falsestores the rules but pauses them (handy while developing).
Origin scoping and auto-lock
origins restricts the grants to the documents you name:
const win = new BrowserWindow({
charter: {
allow: [charterPresets.shell, 'fs:readText'],
origins: [charterPresets.localOrigins], // ['app://*', 'http://localhost:*', …]
},
})
Patterns are globs matched against the full URL. A trailing
*is added when the pattern does not end with one, so a bare origin ('https://example.com') also matches its paths.Empty
origins(the default) means any document — existing apps are unaffected.Auto-lock: as soon as the window navigates to a document outside the list, every grant is refused until it comes back. This is the footgun Electron's preload has (the preload stays injected after navigating) and it is closed here without any app-side URL guard:
charter: the current document is not in the declared origins: https://evil.example/If the backend cannot report the current URL, the check fails closed (nothing is granted). Linux and Windows both report it; note that on Windows
app://documents are navigated ashttps://app.owear/….
Applying at runtime
await win.setCharter({ allow: ['ow-window', 'net'] }) // install / replace
await win.getCharter() // { enforce, allow, deny }
await win.clearCharter() // back to the default
Capabilities can also be dropped mid-session, which is what makes the charter different from a static config file:
await win.setCharter({ allow: ['ow-window', 'fs:readText'] })
// … later, after the untrusted flow is over:
await win.setCharter({ allow: ['ow-window'] })
Presets
charterPresets.shell // ['ow-window', 'theme'] — custom title bar + drags
charterPresets.readOnlyFs // ['fs:readText', 'fs:readFile', 'fs:readDir', …]
charterPresets.node // ['node:call'] — reach app.handle (any handler)
charterPresets.localOrigins // ['app://*', 'http://localhost:*', 'http://127.0.0.1:*']
Use localOrigins for origins so the packaged app and your dev servers are
the only documents that keep the grants.
What happens when a call is refused
The renderer's promise rejects exactly like a module error would:
try {
await ow.invoke('fs', 'writeFile', ['/etc/passwd', 'x'])
} catch (e) {
e.message // "charter: capability 'fs:writeFile' is not granted to this window"
}
The main process also receives an audit event, so a refusal can be logged, surfaced in the UI, or turned into a CI failure:
onCharterDenied(({ windowId, capability, module, fn }) => {
console.warn(`default-deny: ${capability} from window ${windowId}`)
})
Scope of the enforcement
The check happens on the renderer paths only, and each of them is bound to the document the kernel stamped (see Document token below):
| Path | Where |
|---|---|
ow.invoke via postMessage |
Window/Common/Messages.cpp |
ow.invoke via ow-rpc:// (fetch) |
Webview/linux/Backend/Protocols.cpp |
ow.invokeSync via ow-sync:// (XHR) |
Webview/linux/Backend/Protocols.cpp |
WebView2 message / ow-rpc:// (Windows) |
Webview/win/Backend/Handlers.cpp |
The main process is trusted and never filtered, so module.invoke from
@owear/core, the installer API and the updater keep working with a charter
installed.
Three structural properties complete the picture:
- The bridge API only exists in the top frame. Subframes do not get
window.ow. - The channel is bound to that same document. The kernel stamps the injected
script with a per-window secret (kept in a closure, never on
window) and refuses any message that does not carry it. A subframe's rawpostMessageis dropped before it reaches the charter, so it is not even audited. - Embedded webviews are unprivileged by construction. The
webviewmodule never injects the bridge into its child views.
Document token
Nothing to configure: it is automatic. It matters when you audit a denial — a message refused by the charter was sent by your document; a message that never shows up was dropped as unauthenticated (and logged as such).
Granting the Node bridge per handler
Granting node hands the page every handler the main process registered. Name
the handlers instead:
defineCharter({ allow: ['node:myapp.save', 'node:myapp.open'] })
node:call (or node:*) keeps working as the legacy "any handler" grant.
Sandbox
The web process runs with the sandbox enabled explicitly, and the state is logged at startup:
[ow] webview: sandbox del web process: on
That is the OS-level boundary around the process that runs page JS — the
equivalent of Electron's sandbox: true — and it is what contains an engine
exploit, which no JS-world boundary can.
Cost
Measured in benchmarks/charter/RESULTS.md on the same machine as the main
suite: a granted call adds ~1.5% over no charter at all (a lookup), and
a refused one ~10.5%, because every refusal also emits a
charter.denied audit event.