Respect viewer microphone consent and recover permission failures (#105)

Author: phucnguyen1707

apps/mobile/app/(app)/session/[id].tsx

@@ -20,6 +20,7 @@ import { VideoViewer } from '@/components/VideoViewer';
 import { ChatPanel } from '@/components/ChatPanel';
 import { SessionInfo } from '@/components/SessionInfo';
 import { ConnectionBadge } from '@/components/ConnectionBadge';
+import { MicrophoneNotice } from '@/components/MicrophoneNotice';
 
 export default function SessionScreen() {
   const router = useRouter();
@@ -231,7 +232,8 @@ function HostSession({
       </View>
 
       {/* Controls */}
-      <View className="flex-row items-center justify-center gap-4 border-t border-gray-800 px-4 py-3">
+      <MicrophoneNotice failure={webrtc.micFailure} />
+      <View className="flex-row flex-wrap items-center justify-center gap-4 border-t border-gray-800 px-4 py-3">
         {screenShare.isSharing && (
           <TouchableOpacity
             onPress={() => {
@@ -351,7 +353,8 @@ function ViewerSession({
       </View>
 
       {/* Controls */}
-      <View className="flex-row items-center justify-center gap-4 border-t border-gray-800 bg-gray-900 px-4 py-3">
+      <MicrophoneNotice failure={webrtc.micFailure} unmuteRequested={webrtc.unmuteRequested} />
+      <View className="flex-row flex-wrap items-center justify-center gap-4 border-t border-gray-800 bg-gray-900 px-4 py-3">
         {webrtc.connectionState === 'failed' && (
           <TouchableOpacity
             onPress={webrtc.reconnect}

apps/mobile/docs/microphone-consent.md

@@ -0,0 +1,41 @@
+# Mobile microphone consent and recovery
+
+A host mute command can disable the viewer microphone. An unmute command is
+only a request: it shows feedback while the viewer remains muted. Only the
+viewer's local Unmute button changes that intent. Missing or non-boolean mute
+payloads are ignored. Old data-channel callbacks are generation-guarded and
+muted intent survives reconnect, including delayed microphone acquisition.
+
+This does not change the existing initially-enabled microphone preference at
+join, implement a request/acknowledgement protocol, or change host UI optimistic
+mute labels. The host cannot assume a viewer accepted an unmute request.
+
+Host and viewer show listen-only feedback when microphone acquisition fails.
+Only recognized permission errors offer a user-initiated native Settings action;
+unknown device errors are not called permission denials. Opening Settings can
+background the app. The existing foreground-resume path reconnects and
+reacquires the mic: after permission is granted, audio follows the existing
+initially-on preference or the preserved muted intent. A Settings return is
+not a new local-unmute consent gate. There is no permission prompt or acquisition
+caused by an incoming unmute message. Ended tracks are never treated as usable
+when toggling the microphone.
+
+The pinned pnpm patch for react-native-webrtc 124.0.7 forwards permission-chain
+rejections to the caller. Without it, an iOS permission-bridge rejection or a
+synchronous capture-start failure leaves acquisition pending with an unhandled
+rejection. The patch covers Metro source, CommonJS and ESM builds. Host/viewer
+then follow the existing listen-only failure path. Normal user permission
+decisions and successful acquisition are unchanged. A permission dialog the
+user has not answered can still remain pending; this patch is not a timeout or
+native-dialog cancellation mechanism.
+
+`webrtc-permissions.test.ts` executes the installed dependency's JS permission
+chain in all three formats, with only native bridge and stream boundaries
+replaced. It checks grants, denials, bridge rejection and capture-start throws.
+Re-run these tests whenever upgrading WebRTC or changing/removing its patch.
+
+Hook tests cover data-channel payloads, reconnect and permission failures.
+Component and real session-route tests check feedback and local button wiring
+with native APIs mocked. These do not verify native permission dialogs, device
+audio routing, or real WebRTC audio. Before release, check denied/granted mic
+permission, host mute/request-unmute, reconnect and Settings on Android and iOS.

apps/mobile/src/components/MicrophoneNotice.test.tsx

@@ -0,0 +1,81 @@
+import React from 'react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, expect, it, vi } from 'vitest';
+import { Linking, Platform } from 'react-native';
+import { MicrophoneNotice } from './MicrophoneNotice';
+vi.mock('react-native', () => ({
+  View: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  Text: ({ children }: { children?: React.ReactNode }) => <span>{children}</span>,
+  TouchableOpacity: ({
+    children,
+    onPress,
+    accessibilityLabel,
+  }: {
+    children?: React.ReactNode;
+    onPress: () => void;
+    accessibilityLabel: string;
+  }) => (
+    <button onClick={onPress} aria-label={accessibilityLabel}>
+      {children}
+    </button>
+  ),
+  Platform: { OS: 'android' },
+  Linking: { openSettings: vi.fn(async () => {}) },
+}));
+beforeEach(() => {
+  Platform.OS = 'android';
+});
+it('does not open settings automatically and shows requests without enabling a mic', () => {
+  const { rerender } = render(<MicrophoneNotice failure={null} />);
+  expect(screen.queryByText(/microphone/i)).toBeNull();
+  rerender(<MicrophoneNotice failure={null} unmuteRequested />);
+  expect(screen.getByText(/still muted/)).toBeDefined();
+  expect(Linking.openSettings).not.toHaveBeenCalled();
+});
+it.each(['android', 'ios'] as const)(
+  'shows safe listen-only feedback and settings action on %s',
+  async (os) => {
+    Platform.OS = os;
+    render(<MicrophoneNotice failure="permission" />);
+    expect(screen.getByText(/Listen-only/)).toBeDefined();
+    expect(Linking.openSettings).not.toHaveBeenCalled();
+    vi.mocked(Linking.openSettings).mockRejectedValueOnce(new Error('PRIVATE_ERROR'));
+    fireEvent.click(screen.getByRole('button', { name: 'Open microphone settings' }));
+    await waitFor(() => expect(screen.getByText('Could not open Settings.')).toBeDefined());
+    expect(screen.queryByText('PRIVATE_ERROR')).toBeNull();
+  }
+);
+it('does not label an unknown mic failure as denied permission', () => {
+  render(<MicrophoneNotice failure="unavailable" />);
+  expect(screen.getByText('Microphone unavailable. Listen-only mode.')).toBeDefined();
+  expect(screen.queryByRole('button')).toBeNull();
+});
+it('does not offer native Settings on web', () => {
+  Platform.OS = 'web';
+  render(<MicrophoneNotice failure="permission" />);
+  expect(screen.getByText(/Listen-only/)).toBeDefined();
+  expect(screen.queryByRole('button')).toBeNull();
+  expect(Linking.openSettings).not.toHaveBeenCalled();
+});
+it('clears Settings feedback when microphone state changes and ignores late failures', async () => {
+  let reject!: (reason: unknown) => void;
+  vi.mocked(Linking.openSettings).mockReturnValueOnce(
+    new Promise<void>((_, fail) => {
+      reject = fail;
+    })
+  );
+  const { rerender } = render(<MicrophoneNotice failure="permission" />);
+  fireEvent.click(screen.getByRole('button', { name: 'Open microphone settings' }));
+  rerender(<MicrophoneNotice failure={null} unmuteRequested />);
+  await act(async () => {
+    reject(new Error('late'));
+  });
+  expect(screen.queryByText('Could not open Settings.')).toBeNull();
+  rerender(<MicrophoneNotice failure="permission" />);
+  expect(screen.queryByText('Could not open Settings.')).toBeNull();
+  vi.mocked(Linking.openSettings).mockRejectedValueOnce(new Error('current'));
+  fireEvent.click(screen.getByRole('button', { name: 'Open microphone settings' }));
+  await waitFor(() => expect(screen.getByText('Could not open Settings.')).toBeDefined());
+  rerender(<MicrophoneNotice failure="unavailable" />);
+  expect(screen.queryByText('Could not open Settings.')).toBeNull();
+});

apps/mobile/src/components/MicrophoneNotice.tsx

@@ -0,0 +1,54 @@
+import { useEffect, useRef, useState } from 'react';
+import { Linking, Platform, Text, TouchableOpacity, View } from 'react-native';
+import type { MicrophoneFailure } from '../lib/microphone';
+
+export function MicrophoneNotice({
+  failure,
+  unmuteRequested = false,
+}: {
+  failure: MicrophoneFailure | null;
+  unmuteRequested?: boolean;
+}) {
+  const [settingsFailed, setSettingsFailed] = useState(false);
+  const settingsContext = useRef({ attempt: 0, active: true });
+  useEffect(() => {
+    const context = { attempt: 0, active: true };
+    settingsContext.current = context;
+    setSettingsFailed(false);
+    return () => {
+      context.active = false;
+    };
+  }, [failure]);
+  if (!failure && !unmuteRequested) return null;
+  return (
+    <View className="border-t border-gray-800 bg-gray-900 px-4 py-2">
+      <Text accessibilityRole="alert" className="text-sm text-gray-200">
+        {failure === 'permission'
+          ? 'Microphone permission denied. Listen-only mode.'
+          : failure
+            ? 'Microphone unavailable. Listen-only mode.'
+            : 'The host requested unmute. Your microphone is still muted.'}
+      </Text>
+      {failure === 'permission' && (Platform.OS === 'ios' || Platform.OS === 'android') && (
+        <TouchableOpacity
+          accessibilityRole="button"
+          accessibilityLabel="Open microphone settings"
+          className="min-h-11 justify-center self-start py-2"
+          onPress={() => {
+            setSettingsFailed(false);
+            const context = settingsContext.current;
+            const attempt = ++context.attempt;
+            void Linking.openSettings().catch(() => {
+              if (context.active && attempt === context.attempt) setSettingsFailed(true);
+            });
+          }}
+        >
+          <Text className="text-sm text-blue-300">Open Settings</Text>
+        </TouchableOpacity>
+      )}
+      {failure === 'permission' && settingsFailed && (
+        <Text className="text-sm text-gray-200">Could not open Settings.</Text>
+      )}
+    </View>
+  );
+}

apps/mobile/src/components/SessionMicrophone.test.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, expect, it, vi } from 'vitest';
+import SessionScreen from '../../app/(app)/session/[id]';
+
+const state = vi.hoisted(() => ({
+  role: 'viewer',
+  viewer: {
+    micFailure: null as 'permission' | 'unavailable' | null,
+    unmuteRequested: true,
+    hasMic: true,
+    micEnabled: false,
+    connectionState: 'connected',
+    toggleMic: vi.fn(),
+    disconnect: vi.fn(),
+  },
+  host: {
+    micFailure: 'permission' as const,
+    hasMic: false,
+    micEnabled: false,
+    isHosting: true,
+    viewerCount: 0,
+    toggleMic: vi.fn(),
+    startHosting: vi.fn(),
+  },
+}));
+vi.mock('react-native', () => ({
+  View: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  Text: ({ children }: { children?: React.ReactNode }) => <span>{children}</span>,
+  TouchableOpacity: ({
+    children,
+    onPress,
+    accessibilityLabel,
+    disabled,
+  }: {
+    children?: React.ReactNode;
+    onPress: () => void;
+    accessibilityLabel?: string;
+    disabled?: boolean;
+  }) => (
+    <button onClick={onPress} aria-label={accessibilityLabel} disabled={disabled}>
+      {children}
+    </button>
+  ),
+  ActivityIndicator: () => <span>Loading</span>,
+  Alert: { alert: vi.fn() },
+  Platform: { OS: 'android' },
+  Linking: { openSettings: vi.fn(async () => {}) },
+}));
+vi.mock('expo-router', () => ({
+  useRouter: () => ({ back: vi.fn() }),
+  useFocusEffect: vi.fn(),
+  useLocalSearchParams: () => ({ id: 'session-1', role: state.role, participantId: 'viewer-1' }),
+}));
+vi.mock('@/contexts/AuthContext', () => ({ useAuth: () => ({ user: { id: 'user-1' } }) }));
+vi.mock('@/hooks/useWebRTCViewer', () => ({ useWebRTCViewer: () => state.viewer }));
+vi.mock('@/hooks/useWebRTCHost', () => ({ useWebRTCHost: () => state.host }));
+vi.mock('@/hooks/useScreenShare', () => ({ useScreenShare: () => ({ stop: vi.fn() }) }));
+vi.mock('@/hooks/useChat', () => ({ useChat: () => ({ messages: [] }) }));
+vi.mock('@/lib/api/sessions', () => ({
+  sessionApi: { get: vi.fn(async () => ({ data: { join_code: 'ABC' } })) },
+}));
+vi.mock('@/components/VideoViewer', () => ({ VideoViewer: () => null }));
+vi.mock('@/components/ChatPanel', () => ({ ChatPanel: () => null }));
+vi.mock('@/components/SessionInfo', () => ({ SessionInfo: () => null }));
+vi.mock('@/components/ConnectionBadge', () => ({ ConnectionBadge: () => null }));
+beforeEach(() => {
+  state.role = 'viewer';
+  state.viewer.hasMic = true;
+  state.viewer.micFailure = null;
+});
+it('wires a viewer unmute request to feedback but only the local button to toggleMic', async () => {
+  render(<SessionScreen />);
+  await waitFor(() => expect(screen.getByText(/still muted/)).toBeDefined());
+  expect(state.viewer.toggleMic).not.toHaveBeenCalled();
+  fireEvent.click(screen.getByRole('button', { name: 'Unmute' }));
+  expect(state.viewer.toggleMic).toHaveBeenCalledOnce();
+});
+it('keeps leave available and hides unmute when the viewer has no microphone', async () => {
+  state.viewer.hasMic = false;
+  state.viewer.micFailure = 'unavailable';
+  render(<SessionScreen />);
+  await waitFor(() =>
+    expect(screen.getByText('Microphone unavailable. Listen-only mode.')).toBeDefined()
+  );
+  expect(screen.queryByRole('button', { name: 'Unmute' })).toBeNull();
+  expect(screen.getByRole('button', { name: 'Leave' })).toBeDefined();
+});
+it('shows host permission feedback and keeps ending the session available', async () => {
+  state.role = 'host';
+  render(<SessionScreen />);
+  await waitFor(() => expect(screen.getByText(/Microphone permission denied/)).toBeDefined());
+  expect(screen.getByRole('button', { name: 'Open microphone settings' })).toBeDefined();
+  expect(screen.getByRole('button', { name: 'End Session' })).toBeDefined();
+  expect(state.host.toggleMic).not.toHaveBeenCalled();
+});

apps/mobile/src/hooks/useWebRTCHost.test.ts

@@ -54,6 +54,25 @@ vi.mock('../lib/event-source', () => ({
 }));
 
 describe('useWebRTCHost', () => {
+  it.each(['NotAllowedError', 'DeviceError', 'Error'])(
+    'exposes a conservative host mic failure for %s',
+    async (name) => {
+      vi.mocked(mediaDevices.getUserMedia).mockRejectedValueOnce(
+        Object.assign(new Error('PRIVATE'), { name })
+      );
+      const { result } = renderHook(() =>
+        useWebRTCHost({ sessionId: 'session-1', hostId: 'host-1' })
+      );
+      await act(async () => {
+        await result.current.startHosting();
+      });
+      expect(result.current.micFailure).toBe(
+        name === 'NotAllowedError' ? 'permission' : 'unavailable'
+      );
+      expect(result.current.hasMic).toBe(false);
+      expect(createEventSource).toHaveBeenCalled();
+    }
+  );
   beforeEach(() => {
     vi.clearAllMocks();
     mockEventSources.length = 0;