API / Charter (capability policy)

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. deny always wins over allow, so you can grant a whole module and carve out single functions.
  • enforce: false stores 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 as https://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 raw postMessage is dropped before it reaches the charter, so it is not even audited.
  • Embedded webviews are unprivileged by construction. The webview module 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.

See also

Edit this page on GitHub ↗