@desklink/react-native 0.3.1 → 0.4.0

package/README.md

@@ -58,12 +58,12 @@ changes, and trackpad presses reach the desktop as touches.
 ## Use
 
 ```tsx
-import { DesktopView, useDesktopSession, CONTROL_PERMISSIONS } from '@desklink/react-native';
+import { DesktopView, useDesktopSession } from '@desklink/react-native';
 
 const desktop = useDesktopSession({
     authorize: async () => ({
         signaling,                                   // your authenticated channel to the host
-        session: { permissions: CONTROL_PERMISSIONS },
+        session: {},
     }),
 });
 
@@ -78,6 +78,13 @@ desktop.setOrientation('landscape');   // Android only; iOS apps configure suppo
 await desktop.pasteLocalToRemote(await Clipboard.getStringAsync());
 ```
 
+Pairing is the only trust boundary. `authorize` is the app's pairing check: it
+returns a channel to a paired computer or throws, and it runs again on every
+reconnect, so a revoked pairing cannot reopen. A paired session has view,
+input and clipboard; there are no in-app grants, and `session.permissions` is
+ignored. Only the operating system's own consent (screen recording,
+accessibility, a screen-sharing prompt) still applies on the computer.
+
 A screen that only decides *whether* to offer a desktop does not need the
 session: import the flag from its own entry, which is a constant on web and a
 check for the platform module elsewhere, so the hook and the view stay out of
@@ -98,7 +105,7 @@ engine only produces frames on change.
 Keep the encoded picture inside a 1920×1080 box:
 
 ```tsx
-session: { permissions: CONTROL_PERMISSIONS, maxWidth: 1920, maxHeight: 1080 },
+session: { maxWidth: 1920, maxHeight: 1080 },
 ```
 
 The engine never upscales, so a smaller desktop is sent at its own size and a
@@ -212,11 +219,13 @@ heat and battery.
   network is still down. Renegotiation transients from a restart the session
   asked for itself are expected, not a new outage: they neither flip the
   status nor trigger another restart for a short grace window.
-- **Control starts off.** `setInputEnabled(true)` enables pointer, keyboard and
-  clipboard input; `setInputEnabled(false)` blocks new input, releases held keys
-  and buttons, and resets pending gestures. The app decides when to enable it
-  after a deliberate action and must disable it on background or lost readiness;
-  a clipboard write already in flight may still finish.
+- **Input starts disarmed.** This is a local arm against accidental touches,
+  not a permission: the session already has input. `setInputEnabled(true)` arms
+  pointer, keyboard and clipboard input; `setInputEnabled(false)` blocks new
+  input, releases held keys and buttons, and resets pending gestures. The app
+  decides when to arm it after a deliberate action and must disarm it on
+  background or lost readiness; a clipboard write already in flight may still
+  finish.
 - **Released state.** The app disables input on background and unmount;
   session close and a lost control channel release what the desktop was holding.
 - **Explicit clipboard.** Two methods, called on a user action while control is
@@ -278,7 +287,11 @@ What the consuming app — not this package — must get right before review.
 
 `example/` is the smallest app that shows a desktop: a native (non-Expo Go)
 build with `react-native-webrtc`, connecting to `desklink-host bridge` with the
-URL it is launched with. `test/ios-flow.mjs` builds it for the iOS simulator on
+URL it is launched with. Its status line shows plain messages: `Connected`
+once a frame is presented, `Can’t reach your desktop. Reconnecting…` while
+retrying, and `Your desktop ended this session` after revocation. It never
+displays the bridge URL, pairing token, raw failure text or frame metrics.
+`test/ios-flow.mjs` builds it for the iOS simulator on
 a Mac over ssh, serves a private Xvfb desktop from this machine through the
 bridge, and checks that the first frame is presented, that the answer puts
 H.264 first with NACK when the host offers it (VP9 otherwise; both descriptions

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "license": "Apache-2.0",
     "description": "Render and drive a desktop session from a React Native app",
     "main": "index.ts",

package/src/protocol.ts

@@ -16,6 +16,11 @@
 
 export const PROTOCOL_VERSION = 3;
 
+/**
+ * @deprecated Pairing is the only trust boundary: a paired session always has
+ * view, input and clipboard, so there is nothing to ask for. Kept so 0.3 code
+ * compiles; removed at 1.0.
+ */
 export type Permission = 'view' | 'control' | 'clipboard';
 
 /**
@@ -42,7 +47,8 @@ export interface SurfaceGeometry {
 
 export interface SessionOpenRequest {
     cursor?: 'embedded' | 'hidden';
-    permissions: Permission[];
+    /** @deprecated Ignored: a paired session always has view, input and clipboard. */
+    permissions?: Permission[];
     maxWidth?: number;
     maxHeight?: number;
     bitrateKbps?: number;
@@ -127,6 +133,7 @@ export type SessionStatus =
     | 'failed';
 
 export type SessionFailure =
+    /** The app's `authorize()` refused, or the host did: not paired, or the pairing was revoked. */
     | { code: 'permission'; message: string }
     /** Nobody approved the desktop's own screen-sharing prompt in time. */
     | { code: 'consent'; message: string }
@@ -146,6 +153,12 @@ export interface SessionSnapshot {
     geometry: SurfaceGeometry | null;
     /** True once an authorized, current-generation frame has actually rendered. */
     presented: boolean;
+    /**
+     * `message` is free text from the app's `authorize()`, the host or the
+     * engine and may contain a bridge URL or pairing token. Never display it
+     * to people; redact sensitive data before logging it. Choose user-facing
+     * text from the session state and `code` instead.
+     */
     failure: SessionFailure | null;
     /** Redacted diagnostics: codec, route, counters. Never identities. */
     diagnostics: Record<string, string | number | boolean>;

package/src/useDesktopSession.ts

@@ -172,10 +172,10 @@ async function loadPlatform(): Promise<boolean> {
 
 export interface DesktopSessionOptions {
     /**
-     * Ask the owning application for a fresh, short-lived authorization and the
-     * authenticated channel to the host engine. Called for the first connection
-     * and again for a reconnect: the package never reuses authority it was not
-     * granted again.
+     * The app's pairing check: return the authenticated channel to the host
+     * engine of a paired computer, or throw. Pairing is the only trust
+     * boundary, so a paired session has view, input and clipboard. Called again
+     * on every reconnect, so a revoked pairing cannot reopen.
      */
     authorize: () => Promise<{ signaling: Signaling; session: SessionOpenRequest }>;
     onStateChange?: (snapshot: SessionSnapshot) => void;
@@ -717,7 +717,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         let openedResult: SessionOpenResult;
         try {
             openedResult = await authorization.signaling.request<SessionOpenResult>('session.open', {
-                permissions: authorization.session.permissions,
+                // Ignored by 0.4+ engines, whatever the app asked for. A 0.3
+                // engine refuses an open without `view`, so the full set stays
+                // on the wire until 0.3 hosts leave support.
+                permissions: ['view', 'control', 'clipboard'],
                 max_width: authorization.session.maxWidth,
                 ...(authorization.session.cursor === undefined ? {} : { cursor: authorization.session.cursor }),
                 max_height: authorization.session.maxHeight,
@@ -1106,5 +1109,5 @@ function randomId(): string {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 
-/** The permissions a normal remote-control session asks for. */
+/** @deprecated Ignored: a paired session always has view, input and clipboard. Removed at 1.0. */
 export const CONTROL_PERMISSIONS: Permission[] = ['view', 'control', 'clipboard'];