#Camera, microphone and location
Camera, microphone, screen capture and location in Krate Native apps: permission policy, remembered decisions, request handlers and OS consent.
Experimental. Part of Krate Native. The Linux (WebKitGTK) request path is tested end to end with mock capture devices. The macOS (WKWebView) and Windows (WebView2) paths compile and their decision tables are unit-tested, and the CI native job drives their request path, but nothing here has been confirmed on a real Mac or Windows machine. No CI runner has a camera or microphone, so no test records real hardware.
A page asks the webview for the camera, the microphone, screen capture and the
location with getUserMedia, getDisplayMedia and navigator.geolocation.
A browser decides with its own prompt. In a Krate Native app the app
decides: the platform layer hands every such request to the SDK, and nothing
is granted that the app did not allow.
// krate.config.ts
export default {
native: {
media: {
camera: "prompt", // "prompt" (default) | "allow" | "deny"
microphone: "prompt",
screen: "prompt",
location: "deny",
notifications: "prompt",
clipboardRead: "prompt",
remember: true, // keep the answers of the native prompt (default)
usage: { // macOS Info.plist usage descriptions
camera: "Acme shows your camera in video calls.",
microphone: "Acme records your voice in video calls.",
location: "Acme tags notes with where you wrote them.",
screenCapture: "Acme shares your screen in calls.",
},
},
},
};krate native build writes the policy to app.json as media; the shell reads
it once at load.
#How a request is decided
For each request (one getUserMedia({ audio: true, video: true }) is one
request with two kinds on Linux and macOS, two requests on Windows):
- Scope. The window or view that asked must have the matching Krate
permission in its scope:
mediafor camera, microphone and screen capture,locationfor the location,notifyfor notifications andclipboard:readfor reading the clipboard. A request from a view without it is denied, whatever the policy says. The view is the native webview that raised the request, not anything the page sends. - Remembered decisions. A decision stored for the view, then one for the app, answers without asking. A remembered denial denies.
- The request stream. While the app has a handler subscribed
(
onRequestin TypeScript,media.OnRequestin Go), a request nothing remembered goes to it and only to it. It has a minute to answer; silence denies. The answer can be remembered for the app, for the view or not at all. - The policy.
allowanddenydecide.promptshows a native message dialog ("Acme wants to use your camera.", Allow or Deny). With no dialog available (nodialogcapability on the platform) a prompt denies. Go host code can replace the dialog with its own UI throughmedia.SetPrompt. - Operating system consent. An allowed camera, microphone, screen or location request then asks the OS (next section). A refusal there denies the request.
A request type the SDK does not manage is left to the engine (pointer lock, the
sensor and download permissions of WebView2). Request types with no kind (the
WebKitGTK device-info request that enumerateDevices raises before capture is
allowed) are denied, so the page sees device labels only after it holds a
capture permission, as in other browsers.
#Permissions
| Permission | Grants |
|---|---|
media |
the page may use the camera, microphone and screen capture (subject to the steps above); reading the policy, the remembered decisions and the OS consent state |
media:manage |
changing the policy, remembering and forgetting decisions, answering requests, asking the OS, listing screens and windows; implies media |
location |
the page may read the device location |
None is a default. A derived build adds media and location for you: the
build scans the built UI for getUserMedia / getDisplayMedia and for
navigator.geolocation, like it derives permissions from the SDK ids the code
calls, and lists them in app.json (and reports them against
native.permissions as KR7210 when that allowlist lacks them). krate native dev does the same for an app without a native.permissions list; with a list
that lacks the name, the build prints a note, because the shell will deny the
request and the page only sees NotAllowedError. media:manage is never
derived by the scan; the SDK ids the code calls decide it.
#Seeing and changing it from the app
import * as media from "@krate/app/media";
// Decide requests yourself. While this is subscribed, the policy and the
// dialog are not used for kinds nothing remembered.
const stop = media.onRequest(async (req) => {
// req = { id, view, origin, kinds: ["camera", "microphone"] }
const ok = await askMyOwnWay(req.kinds);
return { allow: ok, remember: "app" }; // or a plain true / false
});
await media.getPolicy(); // { camera: "prompt", ... }
await media.setPolicy("location", "deny");
await media.decisions(); // [{ kind, scope: "app" | viewId, allow, at }]
await media.decide("camera", true); // remember without a request
await media.reset("camera"); // forget one kind; reset() forgets all
media.onOutcome((o) => console.log(o.kinds, o.allowed, o.reason));reason says who decided: remembered, policy, prompt, handler, scope,
timeout, os, unknown view, unsupported or no handler.
App-wide decisions are stored in permissions.json in the app data directory
(mode 0600); decisions for a view live as long as the view. A corrupt file is
ignored.
In Go host code (linked into the shell, or in the Go host child, which reaches the shell over its socket):
import "github.com/kratejs/krate/packages/native/sdk/media"
cancel, _ := media.OnRequest(func(r media.Request) media.Verdict {
return media.Verdict{Allow: r.View == "main", Remember: "none"}
})
defer cancel()
media.SetPolicy("microphone", "deny")
ds, _ := media.Decisions()
media.Reset("") // forget everything#Operating system consent
An allowed request still needs the operating system's consent.
| Camera, microphone | Screen | Location | |
|---|---|---|---|
| macOS | AVCaptureDevice authorization status and requestAccess |
CGPreflightScreenCaptureAccess / CGRequestScreenCaptureAccess |
CLLocationManager |
| Windows | capability consent store (HKLM and HKCU CapabilityAccessManager\ConsentStore\webcam, microphone, and NonPackaged for desktop apps), read only |
no switch | ...\ConsentStore\location, read only |
| Linux | the Camera portal (org.freedesktop.portal.Camera.AccessCamera) when the app runs under Flatpak or Snap; otherwise no switch |
the ScreenCast portal, driven by WebKitGTK | GeoClue, driven by WebKitGTK |
media.osStatus(kind) reads the state without prompting (granted, denied,
notDetermined, restricted or unknown) and media.osRequest(kind) shows
the system prompt when there is one. unknown means the system keeps no switch
the app can read, and the request is allowed on from there.
Limits:
- macOS reports screen recording as granted or not yet granted. The first
CGRequestScreenCaptureAccessshows the system prompt; the grant takes effect after the app restarts, so the first screen capture of a fresh install is refused. - Windows has no API that makes an unpackaged desktop app show a consent
prompt;
osRequestreturns the current state. A denied state needs the user in Settings, Privacy and security. - A Linux desktop outside a sandbox has no consent switch for the camera or microphone at all.
#Usage descriptions and capabilities
krate native build finds what the UI uses and krate native package writes
it into the package:
- macOS
Info.plist:NSCameraUsageDescription,NSMicrophoneUsageDescription,NSLocationUsageDescriptionandNSLocationWhenInUseUsageDescription(andNSScreenCaptureUsageDescription) fromnative.media.usage. A feature the UI uses without a sentence gets a generic one, because macOS ends the process otherwise, and the build reports KR7290 (a warning on builds that target macOS). The generated hardened runtime entitlements getcom.apple.security.device.camera,com.apple.security.device.audio-inputandcom.apple.security.personal-information.locationfor the devices the UI uses; without them macOS delivers no data under the hardened runtime and shows no prompt. - Windows MSIX:
<DeviceCapability Name="webcam">,microphoneandlocationfor the devices the UI uses, so a packaged app appears in the Windows privacy settings.
#Screen and window capture
media.sources({ thumbnailWidth }) lists the screens and windows that can be
captured, with PNG thumbnails (media:manage):
| Platform | Listing |
|---|---|
| macOS | CoreGraphics (CGGetActiveDisplayList, CGWindowListCopyWindowInfo, thumbnails from CGDisplayCreateImage and CGWindowListCreateImage). Window titles and images need the Screen Recording permission. ScreenCaptureKit is not used: it is asynchronous and the picker below cannot take its result. |
| Windows | EnumDisplayMonitors and EnumWindows (visible, uncloaked, titled, non-tool windows); thumbnails with GDI (BitBlt, PrintWindow). |
| Linux | not available: the call returns unsupported. Under Wayland and X11 alike WebKitGTK reaches the screen through the ScreenCast portal and PipeWire, whose picker is the only list. |
No engine accepts a source chosen by the app. getDisplayMedia always shows
the system picker (the WebView2 and WKWebView pickers, the ScreenCast portal),
so media.chooseSource(id) returns unsupported everywhere and the list is for
the app's own UI. What the app can do is gate it: a screen capture request is a
permission request of kind screen, decided as above. WebView2 raises it as
ScreenCaptureStarting (ICoreWebView2_27); a runtime without that interface
cannot be gated and its own picker is the only control. WKWebView raises it
through a private WebKit delegate method
(_webView:requestDisplayCapturePermissionForOrigin:initiatedByFrame:withSystemAudio:decisionHandler:).
#Engine details
| Request hook | Notes | |
|---|---|---|
| Linux | permission-request signal of each WebKitWebView: user media (audio, video, display), geolocation, notification and clipboard requests |
The request is kept and answered later, so a dialog can be shown. With no handler the request is denied. The webrtc feature (see Memory) is on when the code mentions getUserMedia, which turns on enable-media-stream. WebKitGTK gets positions from GeoClue; without it an allowed getCurrentPosition fails with POSITION_UNAVAILABLE, which is not a permission error. |
| macOS | KrateUIDelegate: webView:requestMediaCapturePermissionForOrigin:initiatedByFrame:type:decisionHandler: (macOS 12+), the display capture method above, and requestGeolocationPermission... where WebKit calls it |
The decision handler block is copied and called once on the main thread. |
| Windows | PermissionRequested per view, with a deferral; SavesInProfile is turned off (ICoreWebView2PermissionRequestedEventArgs3) so WebView2 never answers a request itself from its profile |
The app owns the remembered decisions. getUserMedia({ audio, video }) raises two events, one per device. |
#Testing
Real devices are not available in CI, so:
- Linux: set
KRATE_NATIVE_MOCK_CAPTURE=1and WebKitGTK uses its mock capture devices (enable-mock-capture-devices); they need the GStreamer base plugins (libgstapp,libgstvideotestsrc) thatlibwebkit2gtkdepends on.TestGUIPermission*inplatform/linuxandTestNativeE2EMediaGUIuse it. - Windows:
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--use-fake-device-for-media-streamgives Chromium fake devices.TestGUIPermission*inplatform/windowsuse it. - macOS: a runner has no camera, so WebKit rejects
getUserMediabefore it asks the app.TestGUIPermissionDelegatecalls the delegate methods of the real web view with blocks of its own, as WebKit does. - In UI tests
@krate/app/testingandcreateFakeHostserve thekrate/media.*ids.
#Known limits
- The macOS and Windows implementations are untested on those systems. The
Objective-C selectors, the WebView2 interfaces (their vtables checked against
WebView2.h) and the registry layout were written from the headers and documentation. - Notifications and clipboard-read requests are routed on Linux and Windows; macOS WKWebView has no public delegate for them.
- A policy of
allowfor the microphone on a page the user does not trust is the app's decision: the SDK does not tell origins apart because the app origin is the only one the navigation lock lets in.
Last updated: 2026-11-17
Contributors: Noinkin