Flutter macOS Tcc Responsible Process Camera Denial

Flutter macOS TCC Responsible-Process Camera Denial

Problem

A Flutter macOS app that should have camera/microphone access shows a black preview (or returns zero frames) even though:

• NSCameraUsageDescription and NSMicrophoneUsageDescription are present in macos/Runner/Info.plist.
• com.apple.security.device.camera and com.apple.security.device.audio-input are true in both DebugProfile.entitlements and Release.entitlements.
• The native camera plugin reports isInitialized: true and returns a texture ID.
• No permission dialog ever appears.
• No errors are logged by the camera plugin or AVFoundation.

The symptom is usually a "timeout fallback" firing in the plugin (e.g. DivineCamera macOS: Initialization completed via timeout, or similar 2-second init guards) because the plugin is waiting for a first sample buffer that never arrives. Camera metadata from the plugin shows iso: 0.0, exposureDuration: 0.0, aperture: 0.0 — the device was enumerated but never actually started delivering samples.

Context / Trigger Conditions

All of the following are true:

1. App was launched via flutter run -d macos (or via flutter run from an IDE that wraps flutter in a terminal — VS Code, Cursor, Android Studio, cmux).
2. The terminal emulator is a hardened-runtime app without camera/mic entitlements in its own code signature.
3. macOS version is 10.15+ (TCC enforcement tightened; affects Big Sur onwards, intensifies on Sequoia/Tahoe).
4. No explicit AVCaptureDevice.requestAccess(for: .video) call in the plugin, OR the call is being attributed to the wrong process.

Specifically, this is NOT:

• flutter-macos-permission-handler-camera-failure (that's about permission_handler plugin silently failing to bridge to TCC).
• flutter-macos-duplicate-camera-plugin (that's a build error).
• A missing Info.plist entry (the usage description IS present).
• A missing entitlement (the entitlement IS present).

Root Cause

macOS TCC attributes permission requests to the responsible process, not the accessing process. When flutter run launches the .app as a child of the terminal, TCC walks the process tree and picks the terminal as the "responsible" party for any protected resource access. This is the same mechanism that causes "Terminal wants access to ..." prompts instead of prompts for individual scripts.

For camera/microphone specifically, TCC enforces that the responsible process has the matching entitlement. If cmux / iTerm / VS Code / etc. is the responsible process and it's hardened-runtime without com.apple.security.device.camera, TCC logs:

tccd: Prompting policy for hardened runtime;
  service: kTCCServiceCamera requires entitlement com.apple.security.device.camera
  but it is missing for responsible={identifier=<terminal>, ...}
  accessing={identifier=<YourApp>, binary_path=.../YourApp.app/Contents/MacOS/YourApp}
tccd: Policy disallows prompt for Sub:{<terminal>}; access to kTCCServiceCamera denied

Critically: TCC will not even show the user a prompt. It silently denies. From the app's perspective, AVCaptureSession.startRunning() returns without error but zero sample buffers are ever produced, so any first-frame timeout in the plugin fires eventually.

Diagnosis

Run this while (or just after) reproducing the failure:

/usr/bin/log show --last 10m --predicate 'subsystem == "com.apple.TCC"' --info 2>&1 \
  | grep -iE "camera|microphone|<YourAppName>|Runner" \
  | tail -40

You are looking for the phrase:

Policy disallows prompt for Sub:{<terminal.bundle.id>}...;
access to kTCCServiceCamera denied

and the AttributionChain showing responsible={identifier=<terminal>} and accessing={identifier=<YourApp>}. Presence of these lines confirms the diagnosis.

Reading the TCC database directly (~/Library/Application Support/com.apple.TCC/TCC.db) will fail with "authorization denied" unless Terminal has Full Disk Access — the log show approach is the reliable way.

Solution

Immediate fix (smoke test)

Launch the .app bundle via Launch Services instead of flutter run. Launch Services makes the app its own responsible process, so TCC will prompt the user and attribute the request to the app itself (which does have the entitlement).

# Build once via flutter
cd <project>/mobile
flutter build macos --debug

# Then launch via `open` — NOT via `flutter run`
open build/macos/Build/Products/Debug/<YourApp>.app

open routes through launchd/LaunchServices, so the responsible process becomes <YourApp> rather than the terminal. On first launch from a state where TCC has no entry for the app, macOS will show the standard permission prompt.

If TCC already cached the denied state

If you had previously launched via flutter run, TCC may have cached a denied entry attributed to the terminal. Reset it:

# Narrow scope: reset only this app's permissions
tccutil reset Camera <your.app.bundle.id>
tccutil reset Microphone <your.app.bundle.id>

# Or broad reset (re-prompts for EVERY app that uses camera/mic):
tccutil reset Camera
tccutil reset Microphone

Then relaunch via open.

Long-term fix (shipping apps)

This issue only affects flutter run from a terminal. Production .app bundles distributed to end users (via DMG, Mac App Store, notarized download) launch via LaunchServices and don't hit this. No code fix is needed for release builds.

For a better developer experience, plugins should call AVCaptureDevice.requestAccess(for: .video) (and .audio) explicitly before starting the capture session. This doesn't change the flutter run TCC outcome (TCC still attributes to the terminal), but it provides a clear granted=false error path instead of a silent frame-timeout.

AVCaptureDevice.requestAccess(for: .video) { videoGranted in
    guard videoGranted else {
        completion(nil, "Camera permission denied")
        return
    }
    AVCaptureDevice.requestAccess(for: .audio) { _ in
        // audio denial can be non-fatal; continue without audio input
        self.sessionQueue.async { self.setupCamera(completion: completion) }
    }
}