Security
Owear gives your UI a direct, powerful bridge to native code. That is the point — and it is also the thing to reason about. This page collects the defaults and the levers you have.
Trust model
- The renderer is your code.
ow.invokecan call any loaded module, includingfs,process, andshell. Treat the bridge like Node'sfsAPI: only your own documents should run in a window that exposes it. - Remote content is untrusted. If you load third-party pages, do not let
them reach native modules without a permission boundary. Prefer webviews
(
webview.*) or a restricted session for external content. - The three rules above are enforced, not conventions, once you declare a charter: the kernel refuses what the policy did not grant, the privileged channel only answers the document it stamped, and the grants stop applying when the window navigates somewhere you did not name.
Capability policy (charter)
The charter is the boundary between your UI and the kernel. It is the piece that replaces Electron's hand-written preload: instead of trusting that the preload exposed little, the kernel refuses what was not granted.
new BrowserWindow({
charter: {
allow: ['ow-window', 'theme', 'fs:readText', 'node:myapp.save'],
origins: [charterPresets.localOrigins], // 'app://*', 'http://localhost:*'
},
})
- Deny by default. Once a window has a charter, anything it did not grant is
refused with
charter: capability '<module>:<fn>' is not granted to this window, and the refusal is audited (onCharterDenied). denybeatsallow, so you can grant a module and carve out functions.- The Node bridge is granted per handler (
node:myapp.save), not as a whole. - Origins lock the grants to your documents. Navigating elsewhere refuses everything until the window comes back — the footgun Electron's preload has.
- The privileged surface is one document. The bridge lives in the top frame only, and the kernel drops any message that does not carry the document token (a subframe cannot use the channel even if it reaches the handler object).
- The web process runs sandboxed (logged at startup as
sandbox del web process: on). That is the boundary that contains an engine exploit — no JS-world rule can.
What is not covered: a compromised engine crosses any JS-level boundary, and the main process is trusted by design (the charter filters the renderer paths only).
Permissions
Web platform features (geolocation, notifications, camera, microphone, clipboard read) are denied by default. Grant them explicitly:
import { session } from '@owear/core'
session.onPermissionRequest(({ permission, origin }) => {
return origin === 'app://index.html' && permission === 'notifications'
})
Opening external content
shell.openExternalaccepts onlyhttp,https, andmailto. Other schemes are refused, which preventsfile://,javascript:, and custom-scheme launches from untrusted links.- Control
window.open/target="_blank"with a window-open handler:
win.webContents.setWindowOpenHandler(({ url }) => {
if (url.startsWith('https://trusted.example')) return { action: 'allow' }
return { action: 'deny' }
})
Custom protocols
app.protocol(name, { privileged }) can mark a scheme secure, cors,
standard, stream, or fetch-capable. Only mark schemes you fully control as
secure; doing so lets pages treat their origin as trustworthy.
The serve form maps a scheme to a directory on disk. The kernel validates paths
to prevent traversal outside the served root.
Shipping content security
- Set a Content-Security-Policy in your HTML. Owear does not inject one for you.
- Prefer
app://overfile://for bundled assets;file://has weaker origin semantics. - Do not expose
node/callhandlers that perform sensitive actions without validating arguments. A handler runs whatever the renderer asks.
Secrets
Store credentials with safeStorage, never in
localStorage or plain files.
Supply chain
- The updater verifies sha256 always, and Ed25519 signatures when a public key is configured. Configure a public key for any distributed app; see Auto-update.
- Installer payloads can carry per-group protection flags (
integrity,readonly,hidden,signed); see Installers.
Checklist
- The window declares a
charterand it lists only what the UI needs. - The charter declares
originsso grants stop when the window navigates. -
session.onPermissionRequestgrants only what you need. -
setWindowOpenHandlerdenies by default. - A CSP is set in
index.html. - Secrets use
safeStorage. - The updater has a public key configured.
- Remote content is isolated (separate webview/session).