fix(darwin): honour Permissions for media capture requests

[leaanthony]

This recovers the implementation that was unintentionally stranded when #6050's temporary base branch was deleted after the documentation migration merged.

The original PR contained real Darwin code and tests, not just documentation:

• WKUIDelegate media-capture permission handling for macOS 12+
• Permissions mapping for camera and microphone requests
• focused Darwin tests for the decision mapping and unknown-window behavior
• the related changelog and M-Press documentation updates
• refreshed translation-audit exceptions for the reviewed platform headings

The original implementation and tests were authored by Stefan (@fan711); this recovery preserves him as co-author. See the original PR: #6050.

Checks

• go test ./pkg/application -skip '^TestX11GlobalShortcutEndToEnd$'
• go test -race ./pkg/application -skip '^TestX11GlobalShortcutEndToEnd$'
• bash docs/mpress/scripts/build.sh
• CodeRabbit review: no findings

The X11 integration test is excluded because this environment does not deliver its synthesized key callback. Native macOS compilation and runtime validation still need to run in macOS CI.

Closes #6067.

Summary by CodeRabbit

• New Features

  • macOS 12+ now supports camera and microphone permission controls through the application’s permissions settings.
  • Camera and microphone access still requires macOS privacy approval and the appropriate usage descriptions.

• Documentation

  • Updated permissions guidance, support tables, media-capture examples, troubleshooting, and translations to explain WebKit and system-level authorization.
  • Added a warning that missing usage descriptions can cause macOS to terminate the app.

• Bug Fixes

  • Fixed camera and microphone permission settings being ignored on macOS 12+.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: wailsapp/wails/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 6307335e-d3bc-4c02-bb9d-3437a4aaf52b

📥 Commits

Reviewing files that changed from the base of the PR and between 1e583ab and 1307a58.

📒 Files selected for processing (1)

• v3/pkg/application/webview_window_darwin.m

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

Walkthrough

macOS 12 and later now apply per-window Permissions to camera and microphone requests through WKUIDelegate. TCC still controls device access. Darwin tests, localized documentation, translation audit data, and the unreleased changelog cover this behavior.

Changes

macOS media permission handling

Layer / File(s)	Summary
Permission resolution v3/pkg/application/permissions_darwin.go	Maps per-window camera and microphone permissions to WebKit prompt, grant, or deny decisions.
WKUIDelegate integration and tests v3/pkg/application/webview_window_darwin.m, v3/pkg/application/permissions_darwin_test.go	Passes WebKit media-capture requests to the Darwin resolver. Tests cover decision precedence, media combinations, default behavior, unknown windows, and temporary application state.
Documentation and release notes docs/mpress/content/..., docs/mpress/translation/audit-exceptions.json, v3/UNRELEASED_CHANGELOG.md	Documents macOS 12+ behavior, TCC device checks, required usage-description keys, unsupported permission types, and app termination without required keys.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant WebContent
  participant WebviewWindowDelegate
  participant resolveMediaCapturePermission
  participant TCC
  WebContent->>WebviewWindowDelegate: Request camera or microphone
  WebviewWindowDelegate->>resolveMediaCapturePermission: Resolve permission for window
  resolveMediaCapturePermission-->>WebviewWindowDelegate: Prompt, grant, or deny
  WebviewWindowDelegate-->>WebContent: Return WebKit decision
  WebContent->>TCC: Request device access

Loading

Suggested reviewers: taliesin-ai

Merge Risk: ⚪ Minimal · up to 1307a

The reviewed changes align macOS camera and microphone policy with the documented WebKit and TCC behavior. No concrete merge-blocking issue is established; native macOS CI should still validate the change.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 1307a

The change is limited to macOS camera and microphone permissions. Explicit allow settings remove a consent prompt for eligible content within the configured window, while system device consent remains required. Native macOS validation is still outstanding.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The direct exposure is camera and microphone capture by eligible web content within a configured macOS window. Requests reaching this delegate inherit that window's policy regardless of supplied origin or frame metadata; operating-system device approval remains a separate application-level boundary.

Security Findings and Attack Paths

• inferred — If untrusted content can make an eligible capture request in a window explicitly configured with PermissionAllow, the request now receives a WebKit grant without the previous prompt. This is the intended whole-window contract, not an established vulnerability: the reviewed evidence does not demonstrate such an untrusted-content route, and TCC approval is still required.

Trust Boundaries and Controls

• observed — The native-to-Go boundary carries a construction-assigned window identity rather than an identity supplied by page content. Explicit denial blocks the requested capability, combined requests cannot override a denial with a grant, and unresolved window policy retains WebKit prompting.

Resilience and Maintainability Implications

• observed — Documentation distinguishes a permission denial from application termination caused by missing camera or microphone usage descriptions, and recommends explicit denial for undeclared capabilities. PermissionDefault remains prompting rather than a substitute for required platform declarations.

Hardening Proposals

• proposed — Applications mixing trusted UI and untrusted remote content could reserve PermissionAllow for trusted-only windows or retain PermissionDefault. Origin-aware capture policy would be optional additional hardening, not a finding established by this PR.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: applying Darwin Permissions settings to media-capture requests.
Description check	✅ Passed	The description provides the change summary, motivation, linked issue, implementation scope, tests run, known test limitations, documentation updates, and macOS CI requirement. It does not reproduce e…
Linked Issues check	✅ Passed	The PR satisfies issue #6067. WebviewWindowDelegate implements the macOS 12+ WKUIDelegate media-capture callback. The callback maps audio and video requests to resolveMediaCapturePermission. The…
Out of Scope Changes check	✅ Passed	The changes remain within issue #6067 scope. The Darwin implementation and tests directly implement and verify macOS camera and microphone permission handling. The changelog, permissions documentation…

Full details: Docstring Coverage

Explanation

Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the camera gate,
The microphone must also wait.
WebKit asks; the rules reply,
While TCC stands close by.
Docs hop onward, clear and bright,
Tests keep every choice in sight.}

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🔵 Needs a closer look

It introduces Darwin-only Objective-C/WebKit delegate behavior that needs macOS CI compilation/runtime verification to confidently approve.

Review effort: Lite
Findings: None

What changed in this PR

This PR restores and completes the macOS (Darwin) implementation of Wails v3 WebviewWindowOptions.Permissions for media capture, ensuring camera/microphone getUserMedia requests on macOS 12+ are decided according to the configured policy (instead of always falling back to WebKit’s default prompt behavior). It also updates the permissions documentation (including translations) and records the fix in the unreleased changelog.

Changes:

• Implement WKUIDelegate media-capture permission handling on macOS 12+ and route decisions through the existing Wails Permissions map.
• Add focused Darwin unit tests covering decision mapping and unknown-window behavior.
• Update the permissions documentation (and translations) plus translation-audit exceptions and the v3 UNRELEASED changelog entry.

File	Description
v3/​UNRELEASED_CHANGELOG.md	Adds a changelog entry documenting the macOS 12+ Permissions fix for camera/microphone capture.
v3/​pkg/​application/​webview_window_darwin.m	Implements the WKUIDelegate media-capture permission request method and forwards decisions to Go.
v3/​pkg/​application/​permissions_darwin.go	Adds Darwin decision logic mapping Permissions → WKPermissionDecision (prompt/grant/deny).
v3/​pkg/​application/​permissions_darwin_test.go	Adds Darwin-only unit tests to pin decision constants and verify strictest-wins/lookup behavior.
docs/​mpress/​translation/​audit-exceptions.json	Refreshes translation audit exceptions for updated platform headings.
docs/​mpress/​content/​features/​windows/​permissions.md	Updates canonical docs to reflect macOS 12+ support for camera/microphone Permissions and the TCC layer.
docs/​mpress/​content/​de/​features/​windows/​permissions.md	German translation update for the revised macOS permissions section.
docs/​mpress/​content/​fr/​features/​windows/​permissions.md	French translation update for the revised macOS permissions section.
docs/​mpress/​content/​id/​features/​windows/​permissions.md	Indonesian translation update for the revised macOS permissions section.
docs/​mpress/​content/​ja/​features/​windows/​permissions.md	Japanese translation update for the revised macOS permissions section.
docs/​mpress/​content/​ko/​features/​windows/​permissions.md	Korean translation update for the revised macOS permissions section.
docs/​mpress/​content/​pt/​features/​windows/​permissions.md	Portuguese translation update for the revised macOS permissions section.
docs/​mpress/​content/​ru/​features/​windows/​permissions.md	Russian translation update for the revised macOS permissions section.
docs/​mpress/​content/​zh-cn/​features/​windows/​permissions.md	Simplified Chinese translation update for the revised macOS permissions section.
docs/​mpress/​content/​zh-tw/​features/​windows/​permissions.md	Traditional Chinese translation update for the revised macOS permissions section.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Grantmartin2002]

Tested this on macOS 26.6.2 (arm64) in our app. We were carrying a vendor patch that added this same delegate, and I swapped it out for this PR with Permissions set to Microphone: Allow and Camera: Deny. No WebKit mic prompt on first use or after relaunching, and the usual TCC prompt still shows up once like it should. Looks good to me.