Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(remote-desktop): lock unattended sessions on idle or client lock

zqchris08617f137da4
diff --git a/apps/desktop/src/main/remote-desktop-viewer/__tests__/connection.test.ts b/apps/desktop/src/main/remote-desktop-viewer/__tests__/connection.test.ts
index a3f022c73d..f201b6ec93 100644
--- a/apps/desktop/src/main/remote-desktop-viewer/__tests__/connection.test.ts
+++ b/apps/desktop/src/main/remote-desktop-viewer/__tests__/connection.test.ts
@@ -571,6 +571,7 @@ it.each([true, false])(
writeClipboard: () => {},
preferences: () => ({
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
@@ -1051,3 +1052,28 @@ describe('代输入 window view', () => {
expect(request.mock.calls.map(([, message]) => message.op)).not.toContain('clipboardSync');
});
});
+
+// Unit: negotiate the host-enforced policy before sending it, and persist live edits.
+it.each([true, false])('negotiates idle protection only for capable hosts: %s', async (supported) => {
+ let preferences = { ...DEFAULT_VIEWER_PREFERENCES };
+ const request = vi.fn(async (_target, message, check): Promise<unknown> => {
+ check();
+ if (message.op === 'capabilities') return { idleLock: supported };
+ if (message.op === 'start') return { lease: 'lease', controlling: false };
+ return {};
+ });
+ const connection = new RemoteViewerConnection({
+ owner: () => 'owner', request, readClipboard: () => '', writeClipboard: () => {},
+ preferences: () => preferences,
+ savePreferences: async (_device, patch) => (preferences = { ...preferences, ...patch }),
+ });
+ connection.bind({ deviceId: 'host', name: 'Computer' });
+ connection.setActive(true);
+ const generation = connection.generation;
+ await connection.request(generation, { op: 'capabilities' });
+ await connection.request(generation, { op: 'start', displayId: '1' });
+ expect(request.mock.calls.at(-1)?.[1].idleTimeoutMinutes).toBe(supported ? 5 : undefined);
+ await connection.preferences(generation, { idleTimeoutMinutes: 1 });
+ expect(request.mock.calls.at(-1)?.[1].idleTimeoutMinutes).toBe(supported ? 1 : undefined);
+ connection.deactivate();
+});
diff --git a/apps/desktop/src/main/remote-desktop-viewer/__tests__/preferences.test.ts b/apps/desktop/src/main/remote-desktop-viewer/__tests__/preferences.test.ts
new file mode 100644
index 0000000000..7ab04688e8
--- /dev/null
+++ b/apps/desktop/src/main/remote-desktop-viewer/__tests__/preferences.test.ts
@@ -0,0 +1,50 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const fixture = vi.hoisted(() => ({ directory: '' }));
+vi.mock('../../appSessionState', () => ({
+ activeOwnerScopeKey: () => fixture.directory,
+ ownerScopedUserDataPath: (name: string) => join(fixture.directory, name),
+}));
+vi.mock('../../logger', () => ({ createLogger: () => ({ info: vi.fn(), warn: vi.fn() }) }));
+import { readViewerPreferences, writeViewerPreferences } from '../preferences';
+
+beforeEach(() => {
+ fixture.directory = mkdtempSync(join(tmpdir(), 'cindy-idle-preferences-'));
+});
+afterEach(() => {
+ rmSync(fixture.directory, { recursive: true, force: true });
+});
+
+// Unit: persisted per-device safety overrides must survive reread without changing legacy toggles.
+it('loads legacy toggles, persists a per-computer duration, and removes the default override', async () => {
+ const file = join(fixture.directory, 'remote-desktop-viewer.json');
+ const key = createHash('sha256').update('computer').digest('hex');
+ writeFileSync(file, JSON.stringify({ [key]: { lockOnExit: true, audio: false } }));
+ expect(readViewerPreferences('computer')).toMatchObject({
+ idleTimeoutMinutes: 5,
+ lockOnExit: true,
+ audio: false,
+ });
+ await writeViewerPreferences('computer', { idleTimeoutMinutes: 1 });
+ expect(readViewerPreferences('computer').idleTimeoutMinutes).toBe(1);
+ expect(readViewerPreferences('other').idleTimeoutMinutes).toBe(5);
+ expect(JSON.parse(readFileSync(file, 'utf8'))[key].idleTimeoutMinutes).toBe(1);
+ await writeViewerPreferences('computer', { idleTimeoutMinutes: 5 });
+ expect(JSON.parse(readFileSync(file, 'utf8'))[key]).not.toHaveProperty('idleTimeoutMinutes');
+ expect(readViewerPreferences('computer')).toMatchObject({
+ idleTimeoutMinutes: 5,
+ lockOnExit: true,
+ audio: false,
+ });
+});
+it('preserves never and rejects invalid durations before writing', async () => {
+ await writeViewerPreferences('computer', { idleTimeoutMinutes: 0 });
+ await expect(writeViewerPreferences('computer', { idleTimeoutMinutes: -1 })).rejects.toThrow(
+ 'INVALID_REQUEST',
+ );
+ expect(readViewerPreferences('computer').idleTimeoutMinutes).toBe(0);
+});
diff --git a/apps/desktop/src/main/remote-desktop-viewer/__tests__/windows.test.ts b/apps/desktop/src/main/remote-desktop-viewer/__tests__/windows.test.ts
index a2f7f458d4..b1a4f5d383 100644
--- a/apps/desktop/src/main/remote-desktop-viewer/__tests__/windows.test.ts
+++ b/apps/desktop/src/main/remote-desktop-viewer/__tests__/windows.test.ts
@@ -1,4 +1,5 @@
import { EventEmitter } from 'node:events';
+import { powerMonitor } from 'electron';
import { afterEach, expect, it, vi } from 'vitest';
const fixture = vi.hoisted(() => ({
windows: [] as any[],
@@ -9,6 +10,7 @@ const fixture = vi.hoisted(() => ({
}));
vi.mock('electron', () => ({
BrowserWindow: { fromWebContents: () => null },
+ powerMonitor: new EventEmitter(),
screen: { getDisplayMatching: () => ({ workArea: { x: 0, y: 0, width: 1920, height: 1080 } }) },
clipboard: { readText: () => '', writeText: vi.fn() },
ipcMain: { handle: (name: string, fn: Function) => fixture.handlers.set(name, fn) },
@@ -115,6 +117,7 @@ import { remoteInvoke } from '../../device-link/index';
let manager: RemoteDesktopViewerWindows;
afterEach(() => {
manager?.reset();
+ powerMonitor.removeAllListeners();
fixture.windows = [];
fixture.calls = [];
fixture.handlers.clear();
@@ -452,3 +455,25 @@ it('keeps the session through native hide/minimize, forwards visibility, and end
expect(call(REMOTE_VIEWER.STATE, win).active).toBe(false);
expect(fixture.calls.filter((c) => c[2][0].op === 'stop')).toHaveLength(1);
});
+
+// Unit: physical controller lock/sleep must retire viewer authority before async stop.
+it.each(['lock-screen', 'suspend'])('ends the remote desktop on local %s without automatic resume', async (signal) => {
+ const sender: any = { id: 100 };
+ manager = new RemoteDesktopViewerWindows((value) => value === sender);
+ manager.register();
+ manager.open(sender, { deviceId: 'a', name: 'Computer' });
+ const win = fixture.windows[0];
+ call(REMOTE_VIEWER.READY, win);
+ call(REMOTE_VIEWER.PRESENTED, win);
+ const { generation } = call(REMOTE_VIEWER.STATE, win);
+ vi.mocked(remoteInvoke).mockResolvedValueOnce({ ok: true, result: { lockOnExit: true, idleLock: true } });
+ await call(REMOTE_VIEWER.REQUEST, win, generation, { op: 'capabilities' });
+ await call(REMOTE_VIEWER.REQUEST, win, generation, { op: 'start', displayId: 'screen' });
+ powerMonitor.emit(signal);
+ expect(call(REMOTE_VIEWER.STATE, win).active).toBe(false);
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(fixture.calls.map((args) => args[2][0])).toContainEqual({ op: 'stop', lease: 'lease-a', lockScreen: true });
+ powerMonitor.emit('unlock-screen');
+ expect(call(REMOTE_VIEWER.STATE, win).active).toBe(false);
+});
diff --git a/apps/desktop/src/main/remote-desktop-viewer/connection.ts b/apps/desktop/src/main/remote-desktop-viewer/connection.ts
index 16dfcd3888..c8d7e0ba46 100644
--- a/apps/desktop/src/main/remote-desktop-viewer/connection.ts
+++ b/apps/desktop/src/main/remote-desktop-viewer/connection.ts
@@ -244,7 +244,13 @@ export class RemoteViewerConnection {
request.op === 'offer' && request.settings
? { ...request, settings: remoteDesktopVideoSettingsWire(request.settings) }
: request.op === 'start' || request.op === 'heartbeat'
- ? { ...request, lockOnExit: this.preferencesValue.lockOnExit }
+ ? {
+ ...request,
+ lockOnExit: this.preferencesValue.lockOnExit,
+ ...(this.caps?.idleLock && !target.handoff
+ ? { idleTimeoutMinutes: this.preferencesValue.idleTimeoutMinutes }
+ : {}),
+ }
: request;
const result = await this.send(outgoing, check);
if (request.op === 'capabilities') {
@@ -402,7 +408,10 @@ export class RemoteViewerConnection {
const reset = value.clipboardSync !== this.preferencesValue.clipboardSync;
this.preferencesValue = value;
this.safetyState.invalidate(reset);
- if (patch.lockOnExit !== undefined && this.lease) {
+ if (
+ (patch.lockOnExit !== undefined || patch.idleTimeoutMinutes !== undefined) &&
+ this.lease
+ ) {
// Saving is local; a slow or failed sync must not leave the switch
// showing the old value. Regular heartbeats also carry this policy.
void this.request(generation, { op: 'heartbeat', lease: this.lease });
@@ -561,9 +570,12 @@ export class RemoteViewerConnection {
},
);
}
- close(generation: number): void {
+ close(generation: number, forceLock = false): void {
this.check(generation);
- const lockScreen = this.preferencesValue.lockOnExit && this.caps?.lockOnExit === true;
+ const lockScreen =
+ !this.target?.handoff &&
+ (forceLock || this.preferencesValue.lockOnExit) &&
+ this.caps?.lockOnExit === true;
// A start reply may arrive after close. Its own cleanup must retain the
// explicit exit policy even if this window has already opened a new target.
if (this.starting) this.starting.lockScreen = lockScreen;
diff --git a/apps/desktop/src/main/remote-desktop-viewer/preferences.ts b/apps/desktop/src/main/remote-desktop-viewer/preferences.ts
index 5ce3cabb0a..f3ac74885a 100644
--- a/apps/desktop/src/main/remote-desktop-viewer/preferences.ts
+++ b/apps/desktop/src/main/remote-desktop-viewer/preferences.ts
@@ -1,3 +1,4 @@
+import { isRemoteDesktopIdleMinutes } from '@cindy/device-link';
import { createHash } from 'node:crypto';
import { activeOwnerScopeKey, ownerScopedUserDataPath } from '../appSessionState';
import { createOverrideSettingsFile } from '../maker-host/override-settings-file';
@@ -21,7 +22,9 @@ const store = createOverrideSettingsFile<Overrides>({
for (const key of Object.keys(
DEFAULT_VIEWER_PREFERENCES,
) as (keyof RemoteViewerPreferences)[]) {
- if (key in value && typeof value[key] === 'boolean') patch[key] = value[key];
+ if (key === 'idleTimeoutMinutes') {
+ if (isRemoteDesktopIdleMinutes(value[key])) patch[key] = value[key];
+ } else if (key in value && typeof value[key] === 'boolean') patch[key] = value[key];
}
result[device] = patch;
}
@@ -49,7 +52,10 @@ export async function writeViewerPreferences(
Array.isArray(patch) ||
Object.entries(patch).some(
([key, value]) =>
- !Object.hasOwn(DEFAULT_VIEWER_PREFERENCES, key) || typeof value !== 'boolean',
+ !Object.hasOwn(DEFAULT_VIEWER_PREFERENCES, key) ||
+ (key === 'idleTimeoutMinutes'
+ ? !isRemoteDesktopIdleMinutes(value)
+ : typeof value !== 'boolean'),
)
)
throw new Error('INVALID_REQUEST');
diff --git a/apps/desktop/src/main/remote-desktop-viewer/windows.ts b/apps/desktop/src/main/remote-desktop-viewer/windows.ts
index 2f6434820c..6dc233738a 100644
--- a/apps/desktop/src/main/remote-desktop-viewer/windows.ts
+++ b/apps/desktop/src/main/remote-desktop-viewer/windows.ts
@@ -2,6 +2,7 @@ import {
BrowserWindow,
clipboard,
ipcMain,
+ powerMonitor,
screen,
type IpcMainInvokeEvent,
type WebContents,
@@ -312,7 +313,23 @@ export class RemoteDesktopViewerWindows {
throwIpcError('PERMISSION_DENIED', 'Invalid viewer');
return entry;
}
+ private readonly endForLocalLock = () => {
+ for (const entry of this.entries) {
+ if (!entry.connection.active) continue;
+ try {
+ entry.connection.close(entry.connection.generation, true);
+ } catch {
+ // An account change can retire the owner between the power event and
+ // its handler. Revoke locally without acting as the previous owner.
+ entry.connection.deactivate();
+ }
+ const win = entry.window;
+ if (win && !win.isDestroyed()) entry.controller.close(win.webContents);
+ }
+ };
register(): void {
+ powerMonitor.on('lock-screen', this.endForLocalLock);
+ powerMonitor.on('suspend', this.endForLocalLock);
ipcMain.handle(REMOTE_VIEWER.OPEN, (event, target) => {
assertTrustedAppRendererEvent(event);
this.open(event.sender, target);
diff --git a/apps/desktop/src/main/remote-desktop/__tests__/controller.test.ts b/apps/desktop/src/main/remote-desktop/__tests__/controller.test.ts
index 59ba87214b..fe46ecdb1f 100644
--- a/apps/desktop/src/main/remote-desktop/__tests__/controller.test.ts
+++ b/apps/desktop/src/main/remote-desktop/__tests__/controller.test.ts
@@ -2032,3 +2032,81 @@ describe('automatic control (autoControl)', () => {
expect(h.controller.state?.controlling).toBe(true);
});
});
+
+// Unit: a live heartbeat previously kept an unattended unlocked desktop open forever.
+// Exercise the production lease/input/tick path with an injected clock, without real waits.
+describe('host-enforced idle lock', () => {
+ async function setup(minutes: number | undefined = 1) {
+ const h = harness();
+ h.deps.lockScreen = vi.fn(async () => {});
+ const { lease } = await h.controller.request('phone', {
+ op: 'start', displayId: '1', control: true,
+ ...(minutes === undefined ? {} : { idleTimeoutMinutes: minutes }),
+ }) as RemoteDesktopLease;
+ const keepAlive = async (ms: number) => {
+ for (let elapsed = 0; elapsed < ms; elapsed += 3000) {
+ h.advance(3000);
+ await h.controller.request('phone', { op: 'heartbeat', lease });
+ }
+ };
+ return { ...h, lease, keepAlive };
+ }
+ it('expires despite heartbeats and release cleanup, and only an explicit reconnect clears it', async () => {
+ const h = await setup();
+ await h.keepAlive(57000);
+ h.controller.input(h.lease, 1, [{ kind: 'release' }]);
+ h.advance(3000);
+ await expect(h.controller.request('phone', { op: 'heartbeat', lease: h.lease })).rejects.toThrow('DESKTOP_IDLE_TIMEOUT');
+ await h.controller.stop();
+ expect(h.deps.lockScreen).toHaveBeenCalledOnce();
+ expect(h.controller.state).toBeNull();
+ await expect(h.controller.request('phone', { op: 'start', displayId: '1', resume: true })).rejects.toThrow('DESKTOP_IDLE_TIMEOUT');
+ await expect(h.controller.request('phone', { op: 'start', displayId: '1' })).resolves.toHaveProperty('lease');
+ });
+ it('renews only on real input, preserves elapsed time on recovery, and expires at the new deadline', async () => {
+ const h = await setup();
+ await h.keepAlive(30000);
+ h.controller.input(h.lease, 1, [{ kind: 'move', x: 0.5, y: 0.5 }]);
+ await h.keepAlive(27000);
+ const resumed = await h.controller.request('phone', { op: 'start', displayId: '1', resume: true, idleTimeoutMinutes: 1 }) as RemoteDesktopLease;
+ for (let i = 0; i < 10; i++) {
+ h.advance(3000);
+ await h.controller.request('phone', { op: 'heartbeat', lease: resumed.lease, idleTimeoutMinutes: 1 });
+ }
+ expect(h.deps.lockScreen).not.toHaveBeenCalled();
+ h.advance(3000);
+ await expect(h.controller.request('phone', { op: 'heartbeat', lease: resumed.lease })).rejects.toThrow('DESKTOP_IDLE_TIMEOUT');
+ await h.controller.stop();
+ expect(h.deps.lockScreen).toHaveBeenCalledOnce();
+ });
+ it('locks on lost heartbeat and forbids unattended recovery even when ordinary exit lock is off', async () => {
+ const h = await setup();
+ h.advance(12000);
+ h.controller.tick();
+ await h.controller.stop();
+ expect(h.deps.lockScreen).toHaveBeenCalledOnce();
+ await expect(h.controller.request('phone', { op: 'start', displayId: '1', resume: true })).rejects.toThrow('DESKTOP_STOPPED');
+ });
+ it.each([0, undefined])('keeps disabled/legacy policy %s unchanged', async (minutes) => {
+ const h = harness();
+ h.deps.lockScreen = vi.fn(async () => {});
+ const { lease } = await h.controller.request('phone', { op: 'start', displayId: '1', ...(minutes === undefined ? {} : { idleTimeoutMinutes: minutes }) }) as RemoteDesktopLease;
+ for (let i = 0; i < 21; i++) {
+ h.advance(3000);
+ await h.controller.request('phone', { op: 'heartbeat', lease });
+ }
+ expect(h.deps.lockScreen).not.toHaveBeenCalled();
+ expect(h.controller.state).not.toBeNull();
+ });
+ it('starts a fresh countdown when enabling a policy on an existing connection', async () => {
+ const h = await setup(0);
+ await h.keepAlive(60000);
+ await h.controller.request('phone', { op: 'heartbeat', lease: h.lease, idleTimeoutMinutes: 1 });
+ await h.keepAlive(57000);
+ expect(h.deps.lockScreen).not.toHaveBeenCalled();
+ h.advance(3000);
+ h.controller.tick();
+ await h.controller.stop();
+ expect(h.deps.lockScreen).toHaveBeenCalledOnce();
+ });
+});
diff --git a/apps/desktop/src/main/remote-desktop/controller.ts b/apps/desktop/src/main/remote-desktop/controller.ts
index d37f3fba1d..e7432d5a13 100644
--- a/apps/desktop/src/main/remote-desktop/controller.ts
+++ b/apps/desktop/src/main/remote-desktop/controller.ts
@@ -30,6 +30,7 @@ export type DesktopStopReason =
| 'authentication-changed'
| 'handoff-ended'
| 'heartbeat-expired'
+ | 'idle-timeout'
| 'peer-offline'
| 'signaling-lost'
| 'peer-closed'
@@ -184,6 +185,8 @@ export class RemoteDesktopController {
peer: string;
readonly sourceDisplayId: string;
expires: number;
+ lastInputAt: number;
+ idleTimeoutMinutes?: number;
diagnostics: {
id: string;
startedAt: number;
@@ -200,6 +203,7 @@ export class RemoteDesktopController {
handoff?: DesktopHandoffWindow;
})
| null = null;
+ private idleStopped = new Set<string>();
private starting = false;
private viewerDisplay: ViewerDisplayHandle | null = null;
private displayRestoring: Promise<void> | null = null;
@@ -313,6 +317,10 @@ export class RemoteDesktopController {
active.backgroundViewing = enabled;
this.deps.videoBackground?.(active.lease, enabled);
}
+ // Idle safety is elapsed time, independent of wall-clock corrections.
+ private idleNow(): number {
+ return this.deps.now?.() ?? performance.now();
+ }
private now(): number {
return this.deps.now?.() ?? Date.now();
}
@@ -346,6 +354,14 @@ export class RemoteDesktopController {
} else if (active.handoff && this.deps.handoffCurrent?.(active.handoff.requestId) === false) {
// The 代输入 request finished: nothing is left to show.
void this.stop(undefined, false, 'handoff-ended');
+ } else if (
+ !this.locking &&
+ active.idleTimeoutMinutes &&
+ this.idleNow() - active.lastInputAt >= active.idleTimeoutMinutes * 60_000
+ ) {
+ this.idleStopped.add(active.peer);
+ this.userStopped.set(active.peer, active.lease);
+ void this.stop(active.peer, true, 'idle-timeout');
} else if (!this.locking && active.expires <= this.now()) {
void this.stop(undefined, undefined, 'heartbeat-expired');
}
@@ -400,6 +416,9 @@ export class RemoteDesktopController {
}
}
if (active && lockScreen && this.deps.lockScreen) {
+ // A protected connection that ends on loss of contact must not recover
+ // unattended and automatically unlock the computer again.
+ if (active.idleTimeoutMinutes) this.userStopped.set(active.peer, active.lease);
this.locking = true;
const cancellation = new AbortController();
this.lockAbort = cancellation;
@@ -452,7 +471,10 @@ export class RemoteDesktopController {
return restoring;
}
private exitLockEnabled(): boolean {
- return (this.active?.lockOnExit ?? this.active?.privacyLockOnExit) === true;
+ return (
+ (this.active?.lockOnExit ?? this.active?.privacyLockOnExit) === true ||
+ Boolean(this.active?.idleTimeoutMinutes)
+ );
}
/** A display change keeps the viewer's video only when it asked and capture can follow. */
private holdVideo(keepVideo: boolean | undefined): boolean {
@@ -729,7 +751,8 @@ export class RemoteDesktopController {
}
private require(peer: string, lease: string) {
this.tick();
- if (this.userStopped.get(peer) === lease) throw new Error('DESKTOP_STOPPED');
+ if (this.userStopped.get(peer) === lease)
+ throw new Error(this.idleStopped.has(peer) ? 'DESKTOP_IDLE_TIMEOUT' : 'DESKTOP_STOPPED');
const active = this.active;
if (!active || active.peer !== peer || active.lease !== lease)
throw new Error('DESKTOP_LEASE_EXPIRED');
@@ -761,6 +784,9 @@ export class RemoteDesktopController {
active.sequence = sequence;
const generation = this.controlGeneration;
this.deps.input(request.events);
+ // Release-only cleanup is generated automatically and is not human activity.
+ if (request.events.some((event) => event.kind !== 'release'))
+ active.lastInputAt = this.idleNow();
// Fresh user activity permits another repair, but an idle crash-looping
// helper cannot repeatedly restart itself after its ready handshake.
if (generation === this.controlGeneration) this.inputRecoveryUsed = false;
@@ -788,6 +814,7 @@ export class RemoteDesktopController {
...caps,
displays: publicDisplays,
automaticReconnect: true,
+ idleLock: Boolean(this.deps.lockScreen),
connectionTakeover: true,
autoControl: caps.canControl === true,
resolutionRestore: Boolean(
@@ -818,7 +845,8 @@ export class RemoteDesktopController {
request: Extract<ReturnType<typeof parseRemoteDesktopRequest>, { op: 'start' }>,
): Promise<RemoteDesktopLease> {
const authenticationSession = this.authenticationSession(peer);
- if (request.resume && this.userStopped.has(peer)) throw new Error('DESKTOP_STOPPED');
+ if (request.resume && this.userStopped.has(peer))
+ throw new Error(this.idleStopped.has(peer) ? 'DESKTOP_IDLE_TIMEOUT' : 'DESKTOP_STOPPED');
if (request.handoff !== undefined && !this.deps.handoffWindow)
throw new Error('DESKTOP_HANDOFF_UNAVAILABLE');
// A window view resumes only as the same request's view; a display view only as itself.
@@ -835,6 +863,8 @@ export class RemoteDesktopController {
(this.active && !request.takeover && !resumesActive)
)
throw new Error('DESKTOP_BUSY');
+ // Recovery must not grant another full idle period.
+ const lastInputAt = resumesActive ? this.active!.lastInputAt : this.idleNow();
this.starting = true;
this.startingPeer = peer;
const generation = this.controlGeneration;
@@ -873,7 +903,8 @@ export class RemoteDesktopController {
throw new Error('DESKTOP_DISABLED');
if (caps.permissions && !desktopPermissionReady(caps.permissions.screenRecording))
throw new Error('DESKTOP_SCREEN_PERMISSION_REQUIRED');
- if (request.resume && this.userStopped.has(peer)) throw new Error('DESKTOP_STOPPED');
+ if (request.resume && this.userStopped.has(peer))
+ throw new Error(this.idleStopped.has(peer) ? 'DESKTOP_IDLE_TIMEOUT' : 'DESKTOP_STOPPED');
if (request.takeover && this.active) {
this.userStopped.set(this.active.peer, this.active.lease);
void this.stop(this.active.peer, false, 'takeover');
@@ -895,7 +926,10 @@ export class RemoteDesktopController {
display = restored.displays.find((d) => d.id === displayId);
if (!display) throw new Error('DESKTOP_DISPLAY_MISSING');
}
- if (!request.resume) this.userStopped.delete(peer);
+ if (!request.resume) {
+ this.userStopped.delete(peer);
+ this.idleStopped.delete(peer);
+ }
const lease: RemoteDesktopLease = handoff
? {
lease: randomUUID(),
@@ -910,6 +944,9 @@ export class RemoteDesktopController {
peer,
sourceDisplayId: display.id,
expires: this.now() + REMOTE_DESKTOP_LEASE_MS,
+ lastInputAt,
+ idleTimeoutMinutes:
+ !handoff && this.deps.lockScreen ? request.idleTimeoutMinutes : undefined,
diagnostics: {
id: createHash('sha256').update(lease.lease).digest('hex').slice(0, 16),
startedAt: this.now(),
@@ -1126,6 +1163,11 @@ export class RemoteDesktopController {
return { ok: true };
}
case 'heartbeat':
+ if (request.idleTimeoutMinutes !== undefined && !active.handoff && this.deps.lockScreen) {
+ if (active.idleTimeoutMinutes !== request.idleTimeoutMinutes)
+ active.lastInputAt = this.idleNow();
+ active.idleTimeoutMinutes = request.idleTimeoutMinutes;
+ }
if (request.lockOnExit !== undefined && !active.handoff)
active.lockOnExit = request.lockOnExit;
active.expires = this.now() + REMOTE_DESKTOP_LEASE_MS;
@@ -1175,6 +1217,7 @@ export class RemoteDesktopController {
)
);
};
+ if (request.op === 'clipboard' || !request.sync) active.lastInputAt = this.idleNow();
this.clipboardPending = true;
try {
if (request.op === 'clipboardContent') {
diff --git a/apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx b/apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx
index 4a7246a452..4d6cad2c43 100644
--- a/apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx
+++ b/apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx
@@ -12,6 +12,8 @@ import {
} from 'lucide-react';
import {
REMOTE_DESKTOP_VIDEO_QUALITIES,
+ REMOTE_DESKTOP_IDLE_MINUTES,
+ REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
type RemoteDesktopDisplayMode,
type RemoteDesktopVideoQuality,
} from '@cindy/device-link';
@@ -732,6 +734,37 @@ export function RemoteDesktopViewerWindow() {
>
{preference('privacyScreen')}
{preference('lockOnExit')}
+ <FormField
+ label={t('remoteDesktop.idleLock')}
+ className="remote-viewer-field"
+ hint={
+ state?.caps && !state.caps.idleLock
+ ? t('remoteDesktop.settingUnsupported')
+ : undefined
+ }
+ >
+ {(field) => (
+ <Select
+ {...field}
+ label={t('remoteDesktop.idleLock')}
+ value={String(
+ state?.preferences.idleTimeoutMinutes ?? REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ )}
+ disabled={!state?.ready || state.closing || !state.caps?.idleLock}
+ options={REMOTE_DESKTOP_IDLE_MINUTES.map((minutes) => ({
+ value: String(minutes),
+ label:
+ minutes === 0
+ ? t('remoteDesktop.idleNever')
+ : t('remoteDesktop.idleMinutes', { count: minutes }),
+ }))}
+ onValueChange={(value) =>
+ void controller.current?.preference({ idleTimeoutMinutes: Number(value) })
+ }
+ onOpenChange={onSelectOpenChange}
+ />
+ )}
+ </FormField>
<div className="remote-viewer-panel-section">
{state && (
<>
diff --git a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerControl.test.ts b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerControl.test.ts
index dcd5dfeb2e..246f385cef 100644
--- a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerControl.test.ts
+++ b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerControl.test.ts
@@ -244,6 +244,7 @@ const syncOn = async (clipboardSync: RemoteDesktopViewerApi['clipboardSync']) =>
clipboardSync,
preferences: async () => ({
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: true,
@@ -346,6 +347,7 @@ it('a display switch that drops and regains control without a reconnect drops th
clipboardSync,
preferences: async () => ({
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: true,
diff --git a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerLifecycle.test.ts b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerLifecycle.test.ts
index 0cb5a432fe..0c4f485351 100644
--- a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerLifecycle.test.ts
+++ b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerLifecycle.test.ts
@@ -41,6 +41,7 @@ afterEach(() => {
async function fixture(
options: {
+ idleLock?: boolean;
legacyTimeout?: boolean;
delayStart?: boolean;
busy?: boolean;
@@ -67,6 +68,7 @@ async function fixture(
if (options.legacyTimeout && ++capabilityAttempts === 1) throw new Error('INVOKE_TIMEOUT');
return {
version: 1,
+ idleLock: options.idleLock,
enabled: true,
canControl: true,
connectionTakeover: true,
@@ -83,7 +85,7 @@ async function fixture(
startAttempts++;
if (options.busy && !request.takeover) throw new Error('DESKTOP_BUSY');
if (options.delayStart && startAttempts === 1) await start.promise;
- if (hostLease) throw new Error('DESKTOP_BUSY');
+ if (hostLease && !(request.resume && options.idleLock)) throw new Error('DESKTOP_BUSY');
hostLease = 'lease-' + request.displayId;
return {
lease: hostLease,
@@ -446,3 +448,28 @@ it('waits for an established lease to stop before a replacement Renderer starts'
expect(snapshot).toMatchObject({ ready: true, error: null, controlling: true });
expect(current.hostLease()).toBe('lease-one');
});
+
+// Unit: a timeout is terminal even while the link is healthy; reconnect must be explicit.
+it('never automatically reconnects after the host idle deadline', async () => {
+ const current = await fixture({ heartbeat: async () => { throw new Error('DESKTOP_IDLE_TIMEOUT'); } });
+ runtime.post?.({ type: 'streaming', epoch: 'lease-one' });
+ await vi.advanceTimersByTimeAsync(3000);
+ expect(snapshot.error).toBe('idleDisconnected');
+ await vi.advanceTimersByTimeAsync(60000);
+ expect(current.requests.filter((r) => r.op === 'start')).toHaveLength(1);
+});
+
+// Unit: automatic media recovery must not stop the host's running idle clock.
+it('retains the protected host lease while retrying a transient connection failure', async () => {
+ let first = true;
+ const current = await fixture({ idleLock: true, heartbeat: async () => {
+ if (first) { first = false; throw new Error('DESKTOP_LEASE_EXPIRED'); }
+ return { controlling: true };
+ } });
+ runtime.post?.({ type: 'streaming', epoch: 'lease-one' });
+ await vi.advanceTimersByTimeAsync(3000);
+ expect(snapshot.error).toBeNull();
+ expect(current.requests.filter((r) => r.op === 'stop')).toHaveLength(0);
+ await vi.advanceTimersByTimeAsync(3000);
+ expect(current.requests.filter((r) => r.op === 'start').at(-1)).toMatchObject({ resume: true, idleTimeoutMinutes: 5 });
+});
diff --git a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx
index 11ac868fba..2dcd20a0c8 100644
--- a/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx
+++ b/apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx
@@ -97,6 +97,7 @@ it.each(clipboardNotices)('shows %s briefly without retry', async (notice) => {
caps: null,
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: true,
@@ -206,6 +207,7 @@ it('confirms toolbar and native exits, keeps cancellation connected, and discard
ready: true,
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
@@ -288,6 +290,7 @@ it('hides view-only controls and enables desktop actions only after control is c
const state: ViewerSnapshot = {
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
@@ -447,6 +450,7 @@ it.each([
lifecycle.update?.({
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
@@ -496,6 +500,7 @@ it('announces an active privacy screen without a banner or toolbar setting marke
lifecycle.update?.({
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: true,
hostMute: false,
clipboardSync: true,
@@ -675,6 +680,7 @@ it('splits display size into a ratio choice and recommended resolutions for this
ready: true,
preferences: {
audio: false,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
@@ -772,6 +778,7 @@ it('explains why a manual clipboard transfer failed and clears it on the next at
lifecycle.update?.({
preferences: {
audio: true,
+ idleTimeoutMinutes: 5,
privacyScreen: false,
hostMute: false,
clipboardSync: false,
diff --git a/apps/desktop/src/renderer/features/remote-desktop/viewerController.ts b/apps/desktop/src/renderer/features/remote-desktop/viewerController.ts
index 00f0e17be7..03de5dfa19 100644
--- a/apps/desktop/src/renderer/features/remote-desktop/viewerController.ts
+++ b/apps/desktop/src/renderer/features/remote-desktop/viewerController.ts
@@ -390,7 +390,7 @@ export class DesktopViewerController {
if (this.scope === scope && !this.disposed) void this.connect();
})();
}
- private cancel(preserveFrame = false): void {
+ private cancel(preserveFrame = false, preserveLease = false): void {
this.epoch++;
this.heartbeats = new DesktopHeartbeatHistory();
this.lastRequestFailure = null;
@@ -414,7 +414,7 @@ export class DesktopViewerController {
this.abandonChannelRequests();
this.media.reset();
this.runtime?.receive({ type: 'releaseInput' });
- void this.session.stop().catch(() => {});
+ void this.session.stop(false, preserveLease).catch(() => {});
this.runtime?.receive({ type: 'stop', preserveFrame });
this.publish({
controlling: false,
@@ -512,7 +512,13 @@ export class DesktopViewerController {
(/DESKTOP_(VIEW_ONLY|INPUT_(BUSY|UNSUPPORTED|UNAVAILABLE|TIMEOUT))/.test(code)
? 'controlUnavailable'
: null);
- this.cancel(true);
+ this.cancel(
+ true,
+ !blocked &&
+ this.state.caps?.idleLock === true &&
+ this.state.caps.automaticReconnect === true &&
+ this.state.preferences.idleTimeoutMinutes > 0,
+ );
this.publish({ status: 'reconnecting', error: blocked });
this.retryAt = Date.now() + this.retryDelay;
this.retryDelay = Math.min(15000, this.retryDelay * 2);
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 23faf12e88..0ca584cc22 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -1200,8 +1200,13 @@
"clipboardSyncPermission": "Clipboard sync needs paste access. Allow it, then return to this window to resume.",
"clipboardSyncWaiting": "The remote computer’s clipboard is not available right now (it may be locked). Sync resumes automatically.",
"lockingOnExit": "Locking computer…",
+ "idleLock": "Disconnect and lock when idle",
+ "idleNever": "Never",
+ "idleMinutes_one": "{{count}} minute",
+ "idleMinutes_other": "{{count}} minutes",
+ "idleDisconnected": "Disconnected due to inactivity. Reconnect when you are ready.",
"lockOnExit": "Lock Computer on Exit",
- "lockOnExitHint": "Locks when you leave remote desktop. Reconnecting or switching apps does not lock the computer.",
+ "lockOnExitHint": "Locks the computer when you exit remote desktop.",
"lockOnExitFailed": "Could not confirm that the computer locked. Check the computer before leaving it unattended.",
"nativeResolution": "Native",
"autoUnlock": "Automatically unlock computer",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index e4598e2730..a6e55e6e51 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -1188,8 +1188,12 @@
"clipboardSyncPermission": "クリップボード同期にはペーストの許可が必要です。許可後、このウィンドウに戻ると再開します。",
"clipboardSyncWaiting": "リモートのパソコンのクリップボードに現在アクセスできません(ロック中の可能性があります)。自動で同期を再開します。",
"lockingOnExit": "コンピューターをロック中…",
+ "idleLock": "操作がない場合に切断してロック",
+ "idleNever": "しない",
+ "idleMinutes_other": "{{count}} 分",
+ "idleDisconnected": "操作がなかったため切断しました。再接続してください。",
"lockOnExit": "終了時にパソコンをロック",
- "lockOnExitHint": "リモートデスクトップを終了するとロックします。再接続やアプリ切り替えではロックしません。",
+ "lockOnExitHint": "リモートデスクトップを終了すると、このコンピュータをロックします。",
"lockOnExitFailed": "パソコンのロックを確認できませんでした。パソコンの状態を確認してください。",
"nativeResolution": "ネイティブ",
"autoUnlock": "コンピューターを自動ロック解除",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 956394c187..299464aed0 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -1188,8 +1188,12 @@
"clipboardSyncPermission": "클립보드 동기화에는 붙여넣기 권한이 필요합니다. 허용한 후 이 창으로 돌아오면 재개됩니다.",
"clipboardSyncWaiting": "원격 컴퓨터의 클립보드에 지금은 접근할 수 없습니다(잠겨 있을 수 있음). 자동으로 동기화를 재개합니다.",
"lockingOnExit": "컴퓨터를 잠그는 중…",
+ "idleLock": "미사용 시 연결 해제 및 잠금",
+ "idleNever": "안 함",
+ "idleMinutes_other": "{{count}}분",
+ "idleDisconnected": "장시간 조작이 없어 연결이 해제되었습니다. 다시 연결해 주세요.",
"lockOnExit": "종료 시 컴퓨터 잠금",
- "lockOnExitHint": "원격 데스크톱을 종료하면 잠급니다. 재연결이나 앱 전환 시에는 잠그지 않습니다.",
+ "lockOnExitHint": "원격 데스크톱을 종료하면 이 컴퓨터를 잠급니다.",
"lockOnExitFailed": "컴퓨터가 잠겼는지 확인하지 못했습니다. 컴퓨터 상태를 확인해 주세요.",
"nativeResolution": "기본 해상도",
"autoUnlock": "컴퓨터 자동 잠금 해제",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 56e885f84a..3e9954d242 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -1188,8 +1188,12 @@
"clipboardSyncPermission": "剪贴板同步需要粘贴权限,授权后回到窗口即可恢复",
"clipboardSyncWaiting": "远程电脑的剪贴板暂时无法访问(可能已锁屏),解锁后会自动继续同步。",
"lockingOnExit": "正在锁定电脑…",
+ "idleLock": "无操作后断开并锁屏",
+ "idleNever": "永不",
+ "idleMinutes_other": "{{count}} 分钟",
+ "idleDisconnected": "已因长时间无操作断开,请重新连接。",
"lockOnExit": "退出后锁定电脑",
- "lockOnExitHint": "退出远程桌面时锁屏。重连或切换 App 不会触发。",
+ "lockOnExitHint": "主动退出远程桌面时锁屏。",
"lockOnExitFailed": "未能确认电脑已锁屏,请检查电脑的锁屏状态。",
"nativeResolution": "原生",
"autoUnlock": "自动解锁电脑",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 8fa3a3cadf..f3f01f56f1 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -1188,8 +1188,12 @@
"clipboardSyncPermission": "剪貼簿同步需要貼上權限,授權後回到視窗即可恢復",
"clipboardSyncWaiting": "遠端電腦的剪貼簿暫時無法存取(可能已鎖定螢幕),解鎖後會自動繼續同步。",
"lockingOnExit": "正在鎖定電腦…",
+ "idleLock": "閒置後中斷並鎖定螢幕",
+ "idleNever": "永不",
+ "idleMinutes_other": "{{count}} 分鐘",
+ "idleDisconnected": "已因長時間無操作中斷,請重新連線。",
"lockOnExit": "退出後鎖定電腦",
- "lockOnExitHint": "離開遠端桌面時鎖定螢幕。重新連線或切換 App 不會觸發。",
+ "lockOnExitHint": "主動離開遠端桌面時鎖定螢幕。",
"lockOnExitFailed": "無法確認電腦已鎖定螢幕,請檢查電腦狀態。",
"nativeResolution": "原生",
"autoUnlock": "自動解鎖電腦",
diff --git a/apps/desktop/src/shared/remoteDesktopViewer.ts b/apps/desktop/src/shared/remoteDesktopViewer.ts
index a6da588dd9..7181d3027a 100644
--- a/apps/desktop/src/shared/remoteDesktopViewer.ts
+++ b/apps/desktop/src/shared/remoteDesktopViewer.ts
@@ -1,3 +1,4 @@
+import { REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES } from '@cindy/device-link';
import type { DesktopIceServer, RemoteDesktopRequest } from '@cindy/device-link';
export const REMOTE_VIEWER = {
@@ -44,6 +45,7 @@ export interface RemoteViewerPreferences {
hostMute: boolean;
clipboardSync: boolean;
lockOnExit: boolean;
+ idleTimeoutMinutes: number;
}
export const DEFAULT_VIEWER_PREFERENCES: RemoteViewerPreferences = {
audio: true,
@@ -51,6 +53,7 @@ export const DEFAULT_VIEWER_PREFERENCES: RemoteViewerPreferences = {
hostMute: false,
clipboardSync: false,
lockOnExit: false,
+ idleTimeoutMinutes: REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
};
export interface RemoteViewerSafety {
privacyActive: boolean;
diff --git a/apps/mobile/src/i18n/locales/en/remoteDesktop.json b/apps/mobile/src/i18n/locales/en/remoteDesktop.json
index 5aae7f2db6..7d7fa0eb9a 100644
--- a/apps/mobile/src/i18n/locales/en/remoteDesktop.json
+++ b/apps/mobile/src/i18n/locales/en/remoteDesktop.json
@@ -168,8 +168,14 @@
"biometricVerificationHint": "Verify your identity before using the saved password.",
"autoUnlockStorageHint": "The password is stored encrypted on this device only. Settings and passwords do not sync with your account.",
"autoUnlockUnavailable": "Automatic unlock is unavailable. You can still connect and unlock the computer manually.",
+ "idleLock": "Disconnect and lock when idle",
+ "idleNever": "Never",
+ "idleMinutes_one": "{{count}} minute",
+ "idleMinutes_other": "{{count}} minutes",
+ "idleDisconnected": "Disconnected due to inactivity. Reconnect when you are ready.",
+ "backgroundDisconnected": "Remote desktop ended when Cindy went into the background. Reconnect to continue.",
"lockOnExit": "Lock Computer on Exit",
- "lockOnExitHint": "Locks when you leave remote desktop. Reconnecting or switching apps does not lock the computer.",
+ "lockOnExitHint": "Locks the computer when you exit remote desktop.",
"lockOnExitFailed": "Could not confirm that the computer locked. Check the computer before leaving it unattended.",
"hostMute": "Mute remote computer",
"hostMuteHint": "Mute the remote computer while connected",
diff --git a/apps/mobile/src/i18n/locales/ja/remoteDesktop.json b/apps/mobile/src/i18n/locales/ja/remoteDesktop.json
index 3ad015eda0..970d630439 100644
--- a/apps/mobile/src/i18n/locales/ja/remoteDesktop.json
+++ b/apps/mobile/src/i18n/locales/ja/remoteDesktop.json
@@ -168,8 +168,13 @@
"biometricVerificationHint": "保存したパスワードを使う前に本人確認を行います。",
"autoUnlockStorageHint": "パスワードはこの端末にのみ暗号化して保存されます。設定とパスワードはアカウントに同期されません。",
"autoUnlockUnavailable": "自動ロック解除を利用できません。接続してパソコンを手動でロック解除できます。",
+ "idleLock": "操作がない場合に切断してロック",
+ "idleNever": "しない",
+ "idleMinutes_other": "{{count}} 分",
+ "idleDisconnected": "操作がなかったため切断しました。再接続してください。",
+ "backgroundDisconnected": "Cindy がバックグラウンドに移ったため、リモートデスクトップを切断しました。再接続してください。",
"lockOnExit": "終了時にパソコンをロック",
- "lockOnExitHint": "リモートデスクトップを終了するとロックします。再接続やアプリ切り替えではロックしません。",
+ "lockOnExitHint": "リモートデスクトップを終了すると、このコンピュータをロックします。",
"lockOnExitFailed": "パソコンのロックを確認できませんでした。パソコンの状態を確認してください。",
"hostMute": "リモートのパソコンをミュート",
"hostMuteHint": "接続中はリモートのパソコンの音声をミュートします",
diff --git a/apps/mobile/src/i18n/locales/ko/remoteDesktop.json b/apps/mobile/src/i18n/locales/ko/remoteDesktop.json
index a54246e3ce..ae1b9f1245 100644
--- a/apps/mobile/src/i18n/locales/ko/remoteDesktop.json
+++ b/apps/mobile/src/i18n/locales/ko/remoteDesktop.json
@@ -168,8 +168,13 @@
"biometricVerificationHint": "저장된 암호를 사용하기 전에 본인 인증을 합니다.",
"autoUnlockStorageHint": "암호는 현재 기기에만 암호화되어 저장됩니다. 설정과 암호는 계정에 동기화되지 않습니다.",
"autoUnlockUnavailable": "자동 잠금 해제를 사용할 수 없습니다. 연결한 뒤 컴퓨터를 수동으로 잠금 해제할 수 있습니다.",
+ "idleLock": "미사용 시 연결 해제 및 잠금",
+ "idleNever": "안 함",
+ "idleMinutes_other": "{{count}}분",
+ "idleDisconnected": "장시간 조작이 없어 연결이 해제되었습니다. 다시 연결해 주세요.",
+ "backgroundDisconnected": "Cindy가 백그라운드로 전환되어 원격 데스크톱 연결이 해제되었습니다. 다시 연결해 주세요.",
"lockOnExit": "종료 시 컴퓨터 잠금",
- "lockOnExitHint": "원격 데스크톱을 종료하면 잠급니다. 재연결이나 앱 전환 시에는 잠그지 않습니다.",
+ "lockOnExitHint": "원격 데스크톱을 종료하면 이 컴퓨터를 잠급니다.",
"lockOnExitFailed": "컴퓨터가 잠겼는지 확인하지 못했습니다. 컴퓨터 상태를 확인해 주세요.",
"hostMute": "원격 컴퓨터 음소거",
"hostMuteHint": "연결 중 원격 컴퓨터의 소리를 음소거합니다",
diff --git a/apps/mobile/src/i18n/locales/zh-CN/remoteDesktop.json b/apps/mobile/src/i18n/locales/zh-CN/remoteDesktop.json
index c7dafaaea8..95805ba011 100644
--- a/apps/mobile/src/i18n/locales/zh-CN/remoteDesktop.json
+++ b/apps/mobile/src/i18n/locales/zh-CN/remoteDesktop.json
@@ -168,8 +168,13 @@
"biometricVerificationHint": "使用保存的密码前,验证你的身份。",
"autoUnlockStorageHint": "密码仅加密保存在当前设备。设置和密码不随账号同步。",
"autoUnlockUnavailable": "暂时无法自动解锁。你仍可连接,并手动解锁电脑。",
+ "idleLock": "无操作后断开并锁屏",
+ "idleNever": "永不",
+ "idleMinutes_other": "{{count}} 分钟",
+ "idleDisconnected": "已因长时间无操作断开,请重新连接。",
+ "backgroundDisconnected": "Cindy 进入后台,远程桌面已断开,请重新连接。",
"lockOnExit": "退出后锁定电脑",
- "lockOnExitHint": "退出远程桌面时锁屏。重连或切换 App 不会触发。",
+ "lockOnExitHint": "主动退出远程桌面时锁屏。",
"lockOnExitFailed": "未能确认电脑已锁屏,请检查电脑的锁屏状态。",
"hostMute": "远程电脑静音",
"hostMuteHint": "连接期间将远程电脑静音",
diff --git a/apps/mobile/src/i18n/locales/zh-TW/remoteDesktop.json b/apps/mobile/src/i18n/locales/zh-TW/remoteDesktop.json
index 313dc70ce9..f7f688f10c 100644
--- a/apps/mobile/src/i18n/locales/zh-TW/remoteDesktop.json
+++ b/apps/mobile/src/i18n/locales/zh-TW/remoteDesktop.json
@@ -168,8 +168,13 @@
"biometricVerificationHint": "使用儲存的密碼前,驗證你的身分。",
"autoUnlockStorageHint": "密碼僅加密儲存在目前裝置。設定和密碼不會隨帳號同步。",
"autoUnlockUnavailable": "暫時無法自動解鎖。你仍可連線,並手動解鎖電腦。",
+ "idleLock": "閒置後中斷並鎖定螢幕",
+ "idleNever": "永不",
+ "idleMinutes_other": "{{count}} 分鐘",
+ "idleDisconnected": "已因長時間無操作中斷,請重新連線。",
+ "backgroundDisconnected": "Cindy 進入背景,遠端桌面已中斷,請重新連線。",
"lockOnExit": "退出後鎖定電腦",
- "lockOnExitHint": "離開遠端桌面時鎖定螢幕。重新連線或切換 App 不會觸發。",
+ "lockOnExitHint": "主動離開遠端桌面時鎖定螢幕。",
"lockOnExitFailed": "無法確認電腦已鎖定螢幕,請檢查電腦狀態。",
"hostMute": "遠端電腦靜音",
"hostMuteHint": "連線期間將遠端電腦靜音",
diff --git a/apps/mobile/src/remote-desktop/RemoteDesktopScreen.tsx b/apps/mobile/src/remote-desktop/RemoteDesktopScreen.tsx
index f4fe210463..0fb32fe143 100644
--- a/apps/mobile/src/remote-desktop/RemoteDesktopScreen.tsx
+++ b/apps/mobile/src/remote-desktop/RemoteDesktopScreen.tsx
@@ -1,4 +1,4 @@
-import { deviceDisplayName } from '@/device-link/deviceName';
+import { deviceDisplayName } from "@/device-link/deviceName";
import { foldDesktopLayout, foldDesktopRegion } from "./foldDesktopLayout";
import { useAdaptiveWindow } from "@/platform/AdaptiveWindowContext";
import { controlRegion } from "@/platform/windowGeometry";
@@ -124,7 +124,10 @@ import { useMouseButtonsPreference } from "./useMouseButtonsPreference";
import { useInputModePreference } from "./useInputModePreference";
import { useAutoUnlockSettings } from "./useAutoUnlockSettings";
import { supportsAutoUnlock } from "./autoUnlockSupport";
-import { useLockOnExitPreference } from "./useLockOnExitPreference";
+import {
+ useLockOnExitPreference,
+ useIdleTimeoutPreference,
+} from "./useLockOnExitPreference";
import { useRemoteDesktopSafety } from "./useRemoteDesktopSafety";
import { useVideoSettingsPreference } from "./useVideoSettingsPreference";
import { usePictureInPicturePreference } from "./usePictureInPicturePreference";
@@ -219,7 +222,10 @@ export default function RemoteDesktopScreen() {
handoff?: string;
}>();
const deviceId = typeof rawId === "string" ? rawId : "";
- const deviceName = deviceDisplayName(deviceId, typeof rawName === "string" ? rawName : undefined);
+ const deviceName = deviceDisplayName(
+ deviceId,
+ typeof rawName === "string" ? rawName : undefined,
+ );
const handoff =
typeof rawHandoff === "string" && rawHandoff ? rawHandoff : undefined;
const router = useRouter();
@@ -307,6 +313,10 @@ export function RemoteDesktopSession({
);
const [lockOnExit, setLockOnExit, lockOnExitLoaded] =
useLockOnExitPreference(deviceId);
+ const [idleTimeoutMinutes, setIdleTimeoutMinutes, idleTimeoutLoaded] =
+ useIdleTimeoutPreference(deviceId);
+ const idleTimeoutPolicy = useRef(idleTimeoutMinutes);
+ idleTimeoutPolicy.current = idleTimeoutMinutes;
const exitLock = useRef(false);
const leaving = useRef(false);
const [isLeaving, setIsLeaving] = useState(false);
@@ -736,7 +746,14 @@ export function RemoteDesktopSession({
const request = useCallback(
async <T,>(message: RemoteDesktopRequest, preSend?: () => void) => {
if (message.op === "start" || message.op === "heartbeat")
- message = { ...message, lockOnExit: exitLockPolicy.current };
+ message = {
+ ...message,
+ lockOnExit: exitLockPolicy.current,
+ ...(capsRef.current?.deviceId === deviceId &&
+ capsRef.current.value.idleLock
+ ? { idleTimeoutMinutes: idleTimeoutPolicy.current }
+ : {}),
+ };
const relay = () =>
linkRef.current.invoke<T>(deviceId, REMOTE_DESKTOP_CHANNEL, [message], {
preSend,
@@ -775,6 +792,13 @@ export function RemoteDesktopSession({
// Local preference remains saved; the regular heartbeat retries sync.
});
};
+ const updateIdleTimeout = (minutes: number) => {
+ setIdleTimeoutMinutes(minutes);
+ idleTimeoutPolicy.current = minutes;
+ const current = active.current;
+ if (current)
+ void request({ op: "heartbeat", lease: current.lease }).catch(() => {});
+ };
const authRef = useRef(auth);
authRef.current = auth;
const loadIceServers = (attemptId: string) =>
@@ -935,7 +959,12 @@ export function RemoteDesktopSession({
}, []);
const stop = useCallback(
- (preserveFrame = false, exiting = false) => {
+ (
+ preserveFrame = false,
+ exiting = false,
+ forceLock = false,
+ preserveLease = false,
+ ) => {
timing.current?.("stopped");
timing.current = null;
generation.current++;
@@ -961,7 +990,13 @@ export function RemoteDesktopSession({
const previous = active.current;
abandonChannelRequests();
icePrefetch.current = null;
- setExitLockPending(Boolean(previous && exiting && exitLock.current));
+ setExitLockPending(
+ Boolean(
+ previous &&
+ ((exiting && exitLock.current) ||
+ (forceLock && capsRef.current?.value.lockOnExit === true)),
+ ),
+ );
active.current = null;
pendingVideoSettings.current = null;
if (previous) pendingMediaOffers.current.delete(previous);
@@ -989,9 +1024,13 @@ export function RemoteDesktopSession({
setKeyboard(false);
setBusy(false);
}
- const lockScreen = Boolean(previous && exiting && exitLock.current);
+ const lockScreen = Boolean(
+ previous &&
+ ((exiting && exitLock.current) ||
+ (forceLock && capsRef.current?.value.lockOnExit === true)),
+ );
return viewerSession
- .current!.stop(lockScreen)
+ .current!.stop(lockScreen, preserveLease)
.then(() => {})
.catch(() => {
if (lockScreen)
@@ -1024,7 +1063,15 @@ export function RemoteDesktopSession({
const blocked = /DESKTOP_STOPPED/.test(code ?? message)
? "hostDisconnected"
: remoteDesktopFailureKey(code ?? message);
- stop(!blocked);
+ stop(
+ !blocked,
+ false,
+ false,
+ !blocked &&
+ capsRef.current?.value.idleLock === true &&
+ capsRef.current.value.automaticReconnect === true &&
+ idleTimeoutPolicy.current > 0,
+ );
setError(blocked);
if (
blocked === "connectionBusy" &&
@@ -1229,6 +1276,7 @@ export function RemoteDesktopSession({
!ready.current ||
!videoPreferencesLoaded ||
!lockOnExitLoaded ||
+ !idleTimeoutLoaded ||
!deviceId ||
AppState.currentState !== "active"
)
@@ -1401,6 +1449,7 @@ export function RemoteDesktopSession({
t,
videoPreferencesLoaded,
lockOnExitLoaded,
+ idleTimeoutLoaded,
viewerSession,
],
);
@@ -1569,7 +1618,11 @@ export function RemoteDesktopSession({
!pipPrepared.current
) {
securityRef.current.resetConnectionAttempt();
- pause();
+ if (idleTimeoutPolicy.current > 0 && capsRef.current?.value.idleLock) {
+ recovery.current.enabled = false;
+ void stopRef.current(false, false, true);
+ setError("backgroundDisconnected");
+ } else pause();
} else if (state === "active" && active.current) {
send({ type: "resume" });
restoreInlinePresentationRef.current();
@@ -1787,7 +1840,13 @@ export function RemoteDesktopSession({
restoreInlinePresentationRef.current();
if (!active.current) void connectRef.current();
}
- }, [focused, pause, videoPreferencesLoaded, lockOnExitLoaded]);
+ }, [
+ focused,
+ pause,
+ videoPreferencesLoaded,
+ lockOnExitLoaded,
+ idleTimeoutLoaded,
+ ]);
useEffect(() => {
send({
type: "theme",
@@ -3601,6 +3660,10 @@ export function RemoteDesktopSession({
lockOnExitAvailable:
lockOnExitLoaded && caps?.lockOnExit === true,
onLockOnExit: updateLockOnExit,
+ idleTimeoutMinutes,
+ idleTimeoutAvailable:
+ idleTimeoutLoaded && caps?.idleLock === true,
+ onIdleTimeout: updateIdleTimeout,
}}
connected={Boolean(lease) && !connectionPending}
controlling={Boolean(lease?.controlling)}
diff --git a/apps/mobile/src/remote-desktop/RemoteDesktopSecuritySettings.tsx b/apps/mobile/src/remote-desktop/RemoteDesktopSecuritySettings.tsx
index eca3ad1748..bfab9ba2e1 100644
--- a/apps/mobile/src/remote-desktop/RemoteDesktopSecuritySettings.tsx
+++ b/apps/mobile/src/remote-desktop/RemoteDesktopSecuritySettings.tsx
@@ -1,5 +1,15 @@
+import {
+ REMOTE_DESKTOP_IDLE_MINUTES,
+ REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+} from "@cindy/device-link";
+import {
+ NativePullDownMenu,
+ usesNativePullDownMenu,
+} from "@/platform/chrome/NativePullDownMenu";
import {
ActivityIndicator,
+ ActionSheetIOS,
+ Pressable,
Platform,
StyleSheet,
View,
@@ -30,6 +40,9 @@ export interface RemoteDesktopSecuritySettingsProps {
notice?: string | null;
onAutoUnlock(value: boolean): void;
onBiometricVerification(value: boolean): void;
+ idleTimeoutMinutes?: number;
+ idleTimeoutAvailable?: boolean;
+ onIdleTimeout?(minutes: number): void;
lockOnExit?: boolean;
lockOnExitAvailable?: boolean;
onLockOnExit?(value: boolean): void;
@@ -54,7 +67,11 @@ export function RemoteDesktopSecuritySettings(
const { t } = useTranslation();
const { colors } = useTheme();
// 说明档(13/18,二级字色);报错说明同字号改用 errorText。
- const hint = { color: colors.textSecondary, fontSize: typeScale.footnote, lineHeight: lineHeight.caption };
+ const hint = {
+ color: colors.textSecondary,
+ fontSize: typeScale.footnote,
+ lineHeight: lineHeight.caption,
+ };
const alertText = { ...hint, color: colors.errorText };
const switchSlot = {
width: 56,
@@ -78,6 +95,10 @@ export function RemoteDesktopSecuritySettings(
const biometricLabel = t(
`remoteDesktop.${Platform.OS === "ios" ? "faceIdVerification" : "biometricVerification"}`,
);
+ const idleLabel = (minutes: number) =>
+ minutes === 0
+ ? t("remoteDesktop.idleNever")
+ : t("remoteDesktop.idleMinutes", { count: minutes });
return (
<View style={{ gap: spacing.sm }}>
{supportsAutoUnlock(props.hostPlatform) && (
@@ -204,7 +225,13 @@ export function RemoteDesktopSecuritySettings(
/>
</View>
<View style={{ flex: 1, gap: spacing.xs }}>
- <Text style={{ color: colors.textPrimary, fontSize: typeScale.body, lineHeight: lineHeight.body }}>
+ <Text
+ style={{
+ color: colors.textPrimary,
+ fontSize: typeScale.body,
+ lineHeight: lineHeight.body,
+ }}
+ >
{t("remoteDesktop.lockOnExit")}
</Text>
<Text style={hint}>
@@ -226,6 +253,73 @@ export function RemoteDesktopSecuritySettings(
/>
</View>
</View>
+ <View style={{ padding: spacing.md, gap: spacing.sm }}>
+ <Text
+ style={{
+ color: colors.textPrimary,
+ fontSize: typeScale.body,
+ lineHeight: lineHeight.body,
+ }}
+ >
+ {t("remoteDesktop.idleLock")}
+ </Text>
+ <NativePullDownMenu
+ disabled={!props.idleTimeoutAvailable}
+ accessibilityLabel={t("remoteDesktop.idleLock")}
+ actions={REMOTE_DESKTOP_IDLE_MINUTES.map((minutes) => ({
+ id: String(minutes),
+ title: idleLabel(minutes),
+ state: minutes === props.idleTimeoutMinutes ? "on" : "off",
+ }))}
+ onAction={(value) => props.onIdleTimeout?.(Number(value))}
+ >
+ <Pressable
+ testID="remoteDesktop.idleLock"
+ disabled={!props.idleTimeoutAvailable}
+ accessibilityRole="button"
+ accessibilityLabel={t("remoteDesktop.idleLock")}
+ accessibilityValue={{
+ text: idleLabel(
+ props.idleTimeoutMinutes ?? REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ ),
+ }}
+ onPress={() => {
+ if (Platform.OS === "ios" && !usesNativePullDownMenu())
+ ActionSheetIOS.showActionSheetWithOptions(
+ {
+ options: [
+ ...REMOTE_DESKTOP_IDLE_MINUTES.map(idleLabel),
+ t("common.cancel"),
+ ],
+ cancelButtonIndex: REMOTE_DESKTOP_IDLE_MINUTES.length,
+ },
+ (index) => {
+ const minutes = REMOTE_DESKTOP_IDLE_MINUTES[index];
+ if (minutes !== undefined) props.onIdleTimeout?.(minutes);
+ },
+ );
+ }}
+ style={{ minHeight: 44, justifyContent: "center" }}
+ >
+ <Text
+ style={{
+ color: props.idleTimeoutAvailable
+ ? colors.inputCaret
+ : colors.textSecondary,
+ fontSize: typeScale.body,
+ lineHeight: lineHeight.body,
+ }}
+ >
+ {props.idleTimeoutAvailable
+ ? idleLabel(
+ props.idleTimeoutMinutes ??
+ REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ )
+ : t("remoteDesktop.settingUnsupported")}
+ </Text>
+ </Pressable>
+ </NativePullDownMenu>
+ </View>
{supportsAutoUnlock(props.hostPlatform) &&
(props.notice || (!props.available && !props.busy)) && (
<Text style={alertText} accessibilityRole="alert">
@@ -269,7 +363,11 @@ export function RemoteDesktopSecuritySettings(
>
<View style={{ flex: 1, gap: spacing.xs }}>
<Text
- style={{ color: colors.textPrimary, fontSize: typeScale.body, lineHeight: lineHeight.body }}
+ style={{
+ color: colors.textPrimary,
+ fontSize: typeScale.body,
+ lineHeight: lineHeight.body,
+ }}
>
{t(`remoteDesktop.${item.key}`)}
</Text>
diff --git a/apps/mobile/src/remote-desktop/__tests__/screen.test.tsx b/apps/mobile/src/remote-desktop/__tests__/screen.test.tsx
index 1aac681ceb..32388cb506 100644
--- a/apps/mobile/src/remote-desktop/__tests__/screen.test.tsx
+++ b/apps/mobile/src/remote-desktop/__tests__/screen.test.tsx
@@ -75,6 +75,7 @@ vi.mock("../useLockOnExitPreference", async (importOriginal) => {
const actual =
await importOriginal<typeof import("../useLockOnExitPreference")>();
return {
+ useIdleTimeoutPreference: actual.useIdleTimeoutPreference,
useRemoteDesktopPreference: () => [false, vi.fn(), true],
useLockOnExitPreference: (deviceId: string) =>
fixture.lockPreferenceFromStorage
@@ -118,6 +119,7 @@ const fixture = vi.hoisted(() => ({
lockOnExit: false,
lockPreferenceFromStorage: false,
lockSupported: true,
+ idleSupported: false,
alert: vi.fn(),
resetUnlockAttempt: vi.fn(),
maybeUnlock: vi.fn(async (_beforeAuthentication?: () => Promise<void>) => {}),
@@ -458,6 +460,7 @@ beforeEach(async () => {
fixture.lockOnExit = false;
fixture.lockPreferenceFromStorage = false;
fixture.lockSupported = true;
+ fixture.idleSupported = false;
fixture.views = {};
fixture.keyboardListeners = {};
fixture.webViewProps = null;
@@ -481,6 +484,7 @@ beforeEach(async () => {
return {
version: 1,
lockOnExit: fixture.lockSupported,
+ idleLock: fixture.idleSupported,
trickleIce: fixture.trickleIce,
automaticReconnect: true,
connectionTakeover: true,
@@ -3478,6 +3482,53 @@ describe("remote desktop controls", () => {
mounted = false;
expect(requests().filter((r) => r.lockScreen)).toHaveLength(1);
});
+ // Unit: the real screen loads per-computer policy before connecting and never
+ // automatically reopens a protected connection after leaving the foreground.
+ it("sends the default idle policy, saves changes, and locks on background without reopening", async () => {
+ fixture.idleSupported = true;
+ fixture.nativeMenus = true;
+ await connect();
+ expect(requests().find((r) => r.op === "start")).toMatchObject({ idleTimeoutMinutes: 5 });
+ act(() => button("operations").click());
+ act(() => button("security").click());
+ await act(async () => (host.querySelector('[data-testid="native-menu.1"]') as HTMLButtonElement).click());
+ expect(storage.items.get("cindy.mobile.remote-desktop.idle-timeout.v1.computer")).toBe("1");
+ expect(requests().filter((r) => r.op === "heartbeat").at(-1)).toMatchObject({ idleTimeoutMinutes: 1 });
+ await act(async () => fixture.appState?.("inactive"));
+ expect(requests().some((r) => r.lockScreen)).toBe(false);
+ await act(async () => fixture.appState?.("background"));
+ expect(requests().filter((r) => r.op === "stop")).toEqual([{ op: "stop", lease: "lease", lockScreen: true }]);
+ await act(async () => fixture.appState?.("active"));
+ await act(async () => vi.advanceTimersByTimeAsync(30_000));
+ expect(requests().filter((r) => r.op === "start")).toHaveLength(1);
+ expect(host.textContent).toContain("remoteDesktop.backgroundDisconnected");
+ });
+ it("keeps the host idle clock alive during a transient protected reconnect", async () => {
+ fixture.idleSupported = true;
+ await connect();
+ const original = fixture.invoke.getMockImplementation()!;
+ let first = true;
+ fixture.invoke.mockImplementation((...args) => {
+ if (args[2][0].op === "heartbeat" && first) {
+ first = false;
+ return Promise.reject(new Error("DESKTOP_LEASE_EXPIRED"));
+ }
+ return original(...args);
+ });
+ await act(async () => vi.advanceTimersByTimeAsync(3000));
+ expect(requests().filter((r) => r.op === "stop")).toHaveLength(0);
+ await act(async () => vi.advanceTimersByTimeAsync(3000));
+ expect(requests().filter((r) => r.op === "start").at(-1)).toMatchObject({ resume: true, idleTimeoutMinutes: 5 });
+ });
+ it("reads an explicit never override before starting a protected-capable host", async () => {
+ act(() => root.unmount());
+ storage.items.set("cindy.mobile.remote-desktop.idle-timeout.v1.computer", "0");
+ fixture.idleSupported = true;
+ root = createRoot(host);
+ await act(async () => root.render(<RemoteDesktopScreen />));
+ await connect();
+ expect(requests().find((r) => r.op === "start")).toMatchObject({ idleTimeoutMinutes: 0 });
+ });
it("does not lock for Face ID inactivity or background recovery", async () => {
fixture.lockOnExit = true;
await act(async () => root.render(<RemoteDesktopScreen />));
@@ -6002,6 +6053,7 @@ describe("remote desktop controls", () => {
});
it.each([
"DESKTOP_STOPPED",
+ "DESKTOP_IDLE_TIMEOUT",
"DESKTOP_DISABLED",
"DESKTOP_ACCESSIBILITY_PERMISSION",
])("does not retry a terminal host decision: %s", async (error) => {
diff --git a/apps/mobile/src/remote-desktop/useLockOnExitPreference.ts b/apps/mobile/src/remote-desktop/useLockOnExitPreference.ts
index de0cc791cb..6cf4418f62 100644
--- a/apps/mobile/src/remote-desktop/useLockOnExitPreference.ts
+++ b/apps/mobile/src/remote-desktop/useLockOnExitPreference.ts
@@ -1,3 +1,7 @@
+import {
+ REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ isRemoteDesktopIdleMinutes,
+} from "@cindy/device-link";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { useCallback, useEffect, useRef, useState } from "react";
@@ -50,3 +54,58 @@ export function useRemoteDesktopPreference(
state.key === key && state.loaded,
] as const;
}
+
+/** Per-computer non-secret override; an absent or invalid value follows the safe default. */
+export function useIdleTimeoutPreference(deviceId: string) {
+ const key = `cindy.mobile.remote-desktop.idle-timeout.v1.${encodeURIComponent(deviceId)}`;
+ const [state, setState] = useState({
+ key,
+ minutes: REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ loaded: false,
+ });
+ const edited = useRef<string | null>(null);
+ useEffect(() => {
+ let active = true;
+ edited.current = null;
+ void writes
+ .then(() => AsyncStorage.getItem(key))
+ .catch(() => null)
+ .then((value) => {
+ const minutes =
+ value === null || !/^\d+$/.test(value)
+ ? REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES
+ : Number(value);
+ if (active && edited.current !== key)
+ setState({
+ key,
+ minutes: isRemoteDesktopIdleMinutes(minutes)
+ ? minutes
+ : REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ loaded: true,
+ });
+ });
+ return () => {
+ active = false;
+ };
+ }, [key]);
+ const update = useCallback(
+ (minutes: number) => {
+ if (!isRemoteDesktopIdleMinutes(minutes)) return;
+ edited.current = key;
+ setState({ key, minutes, loaded: true });
+ writes = writes
+ .then(() =>
+ minutes === REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES
+ ? AsyncStorage.removeItem(key)
+ : AsyncStorage.setItem(key, String(minutes)),
+ )
+ .catch(() => undefined);
+ },
+ [key],
+ );
+ return [
+ state.key === key ? state.minutes : REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES,
+ update,
+ state.key === key && state.loaded,
+ ] as const;
+}
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 8fdb434466..08d9100898 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -1236,6 +1236,21 @@ relay 类型、allowlist 或持久化 schema,服务端无需改动;Mobile
Desktop 本地关窗不等待远端停止回执,后台清理只作用于原 peer / lease,不重置共享链路。
此扩展沿用已有业务通道,不改变 relay、服务端协议或权限范围。
+## 远程桌面闲置锁屏
+
+能力 `idleLock?: boolean` 仅在被控端有原生锁屏能力时声明。新版控制端仅对该能力为真的
+整桌面连接发送 `start` / `heartbeat.idleTimeoutMinutes`,枚举为 0、1、5、10、15、30;
+0 为永不,缺省字段保持旧端行为。控制端本地默认 5 分钟,按电脑持久化 override。
+代输入窗口不协商该能力;旧被控端不显示为已受保护。字段走现有请求解析与鉴权,
+官方与自建 relay 均透明转发,不增加新通道或服务端状态。
+
+被控端按单调时间计时,真实输入与手动剪贴板动作续期,心跳、视频与自动同步不续期。
+闲置到期返回 `DESKTOP_IDLE_TIMEOUT` 并锁屏断开;控制端将其视为终态,只有显式 start
+可恢复。开启闲置保护的连接失联也锁屏,阻止自动 resume。短暂媒体恢复仅撤销控制端
+本地状态、保留有界的被控端 lease,由 resume 保留原倒计时;恢复失败仍在现有 12 秒
+心跳到期处锁屏。不扩展其他 Device Link 通道的故障范围,不因远程桌面结束而断开整条链路。
+普通显式 stop 仍保留旧语义;本机锁屏/睡眠与受保护手机退后台使用已有 stop.lockScreen。
+
## 远程桌面临时分辨率
被控端以可选能力 `resolutionRestore` 声明系统分辨率的连接级恢复支持。
diff --git a/docs/remote-desktop-credentials.md b/docs/remote-desktop-credentials.md
index d454b8e5ba..81f2b1dd84 100644
--- a/docs/remote-desktop-credentials.md
+++ b/docs/remote-desktop-credentials.md
@@ -250,6 +250,15 @@ the phone; Desktop closes locally without awaiting the remote result. Background
lock failures are logged on the host. macOS and supported Linux hosts advertise
this optional capability.
+### Idle protection
+
+The separate default-five-minute idle setting is host-enforced when `idleLock` is
+advertised. It does not change saved credentials, biometric checks or privacy defaults.
+Timeout and loss of the protected lease block automatic resume so saved auto-unlock
+cannot immediately undo locking. Local Desktop lock/suspend requests an immediate
+remote lock; Mobile backgrounding without PiP does the same when idle protection is
+on. See [Remote desktop](remote-desktop.md#idle-protection) for options and counting.
+
### Stable mobile controls
Control, Display and Security share one viewport-sized panel with persistent
diff --git a/docs/remote-desktop.md b/docs/remote-desktop.md
index f91edf6880..c6744e38fd 100644
--- a/docs/remote-desktop.md
+++ b/docs/remote-desktop.md
@@ -1,5 +1,31 @@
# Remote desktop
+## Idle protection
+
+Desktop and Mobile expose **Disconnect and lock when idle** in the remote desktop
+Security panel. Each controller remembers its setting per computer: 1, 5 (default),
+10, 15, 30 minutes, or Never. The host must advertise `idleLock`; older hosts and
+platforms without native screen locking show this setting as unsupported.
+This is separate from default-off lock-on-exit and privacy-screen preferences.
+
+The host counts elapsed time since actual remote input or manual clipboard actions.
+Heartbeats, video frames, automatic clipboard sync and release-key cleanup do not
+reset it. Viewing a static desktop or video without input still counts as idle.
+When the deadline expires, the host revokes input, requests native locking and
+ends the remote desktop. It rejects automatic recovery until a new explicit start.
+Lock failures are logged; the viewer reports disconnection without claiming that
+an unconfirmed native lock succeeded. Single-window input handoffs are excluded.
+
+Desktop controller lock/suspend retires its viewer immediately and requests a host
+lock. With idle protection enabled, Mobile backgrounding without PiP also ends the
+connection and requests a lock; temporary inactive states (such as biometric prompts)
+do not. PiP keeps the same host idle deadline. Neither path automatically reopens the
+remote desktop when the controller returns. If the exit request cannot arrive, the
+host's existing 12-second heartbeat expiry locks the protected lease. A transient
+media reconnect preserves the live host lease and its idle deadline until resume;
+failed recovery reaches heartbeat expiry instead of renewing the idle budget.
+Only this desktop lease ends: other Device Link tasks and channels remain intact.
+
## Desktop viewer
The desktop interaction hierarchy follows a canvas-first approach: device and
diff --git a/packages/device-link/src/__tests__/remoteDesktop.test.ts b/packages/device-link/src/__tests__/remoteDesktop.test.ts
index 141b5a0eda..6190e478a0 100644
--- a/packages/device-link/src/__tests__/remoteDesktop.test.ts
+++ b/packages/device-link/src/__tests__/remoteDesktop.test.ts
@@ -289,3 +289,14 @@ describe("remote desktop viewerHidden", () => {
);
});
});
+
+// Unit: wire compatibility keeps legacy senders unchanged and rejects invalid safety durations.
+it.each([{ op: "start", displayId: "1" }, { op: "heartbeat", lease: "a" }])(
+ "validates the optional idle duration on $op", (request) => {
+ expect(parseRemoteDesktopRequest(request)).toEqual(request);
+ for (const idleTimeoutMinutes of [0, 1, 5, 10, 15, 30])
+ expect(parseRemoteDesktopRequest({ ...request, idleTimeoutMinutes })).toEqual({ ...request, idleTimeoutMinutes });
+ for (const idleTimeoutMinutes of [-1, 0.5, 2, 60, Infinity, NaN, "5", null, true])
+ expect(() => parseRemoteDesktopRequest({ ...request, idleTimeoutMinutes })).toThrow("INVALID_REQUEST");
+ },
+);
diff --git a/packages/device-link/src/remoteDesktop.ts b/packages/device-link/src/remoteDesktop.ts
index efa35c94b3..9f0f115e97 100644
--- a/packages/device-link/src/remoteDesktop.ts
+++ b/packages/device-link/src/remoteDesktop.ts
@@ -11,6 +11,15 @@ import {
/** Additive, same-account business channel. Never broadcast screen data or input. */
export const REMOTE_DESKTOP_CHANNEL = "device-link:remote-desktop:v1";
export const REMOTE_DESKTOP_LEASE_MS = 12_000;
+/** Human inactivity, independent of transport heartbeats. Zero disables it. */
+export const REMOTE_DESKTOP_IDLE_MINUTES = [0, 1, 5, 10, 15, 30] as const;
+export const REMOTE_DESKTOP_DEFAULT_IDLE_MINUTES = 5;
+export function isRemoteDesktopIdleMinutes(value: unknown): value is number {
+ return (
+ typeof value === "number" &&
+ REMOTE_DESKTOP_IDLE_MINUTES.some((minutes) => minutes === value)
+ );
+}
export const REMOTE_DESKTOP_MAX_FRAME_BYTES = 180_000;
export const REMOTE_DESKTOP_MAX_CLIPBOARD_CHARS = 16_384;
@@ -155,6 +164,8 @@ export interface RemoteDesktopCapabilities {
connectionTakeover?: boolean;
/** Can lock the host on exit. New hosts also honor the lease's lockOnExit policy. */
lockOnExit?: boolean;
+ /** Host enforces human inactivity and locks before ending the lease. */
+ idleLock?: boolean;
videoSettings?: boolean;
trickleIce?: boolean;
systemAudio?: boolean;
@@ -265,10 +276,16 @@ export type RemoteDesktopRequest =
takeover?: boolean;
control?: boolean;
lockOnExit?: boolean;
+ idleTimeoutMinutes?: number;
/** 代输入 request id; only to hosts advertising `handoffWindow`. */
handoff?: string;
}
- | { op: "heartbeat"; lease: string; lockOnExit?: boolean }
+ | {
+ op: "heartbeat";
+ lease: string;
+ lockOnExit?: boolean;
+ idleTimeoutMinutes?: number;
+ }
| { op: "stop"; lease: string; lockScreen?: boolean }
| { op: "frame"; lease: string; cursorOverlay?: boolean }
| { op: "control" | "presentation"; lease: string; enabled: boolean }
@@ -313,10 +330,18 @@ export function parseRemoteDesktopRequest(
if (!value || typeof value !== "object" || Array.isArray(value))
throw new Error("INVALID_REQUEST");
const v = value as Record<string, unknown>;
+ const idleTimeout = () => {
+ if (v.idleTimeoutMinutes === undefined) return {};
+ if (!isRemoteDesktopIdleMinutes(v.idleTimeoutMinutes))
+ throw new Error("INVALID_REQUEST");
+ return { idleTimeoutMinutes: v.idleTimeoutMinutes };
+ };
const lockOnExit = () => {
if (v.lockOnExit !== undefined && typeof v.lockOnExit !== "boolean")
throw new Error("INVALID_REQUEST");
- return typeof v.lockOnExit === "boolean" ? { lockOnExit: v.lockOnExit } : {};
+ return typeof v.lockOnExit === "boolean"
+ ? { lockOnExit: v.lockOnExit }
+ : {};
};
// Optional on start and display changes; older hosts drop it and the viewer
// asks for control separately.
@@ -341,7 +366,8 @@ export function parseRemoteDesktopRequest(
throw new Error("INVALID_REQUEST");
if (
v.handoff !== undefined &&
- (typeof v.handoff !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(v.handoff))
+ (typeof v.handoff !== "string" ||
+ !/^[A-Za-z0-9_-]{1,128}$/.test(v.handoff))
)
throw new Error("INVALID_REQUEST");
return {
@@ -352,6 +378,7 @@ export function parseRemoteDesktopRequest(
...(typeof v.resume === "boolean" ? { resume: v.resume } : {}),
...control(),
...lockOnExit(),
+ ...idleTimeout(),
};
}
if (typeof v.lease !== "string" || v.lease.length > 128 || !v.lease)
@@ -438,7 +465,8 @@ export function parseRemoteDesktopRequest(
...(v.lockScreen === true ? { lockScreen: true } : {}),
};
}
- if (v.op === "heartbeat") return { op: v.op, lease, ...lockOnExit() };
+ if (v.op === "heartbeat")
+ return { op: v.op, lease, ...lockOnExit(), ...idleTimeout() };
if (
(v.op === "control" || v.op === "presentation") &&
typeof v.enabled === "boolean"
diff --git a/packages/device-link/src/remoteDesktopViewerSession.ts b/packages/device-link/src/remoteDesktopViewerSession.ts
index c83e31256d..92e8e2dc7d 100644
--- a/packages/device-link/src/remoteDesktopViewerSession.ts
+++ b/packages/device-link/src/remoteDesktopViewerSession.ts
@@ -279,7 +279,10 @@ export class RemoteDesktopViewerSession {
}
}
- stop(lockScreen = false): Promise<unknown> {
+ /** A protected transient retry leaves the bounded host lease running, so its
+ * idle deadline survives. The next start must resume; absent recovery, the
+ * host's heartbeat expiry locks it. Explicit exits always send stop. */
+ stop(lockScreen = false, preserveLease = false): Promise<unknown> {
this.generation++;
const lease = this.active;
this.active = null;
@@ -287,7 +290,7 @@ export class RemoteDesktopViewerSession {
this.controlGeneration++;
this.releaseUnconfirmed = false;
return this.serialize(() =>
- lease
+ lease && (!preserveLease || lockScreen)
? this.request({
op: "stop",
lease: lease.lease,
@@ -395,6 +398,7 @@ export function findRememberedMode(
/** Only transient connection errors may restart a viewer. Explicit stop wins. */
export function remoteDesktopFailureKey(code: string): string | null {
+ if (/DESKTOP_IDLE_TIMEOUT/.test(code)) return "idleDisconnected";
if (/DESKTOP_CONNECTION_TIMEOUT/.test(code)) return "connectionTimeout";
if (/ACCESS_REVOKED/.test(code)) return "accessRevoked";
if (/REMOTE_DISABLED/.test(code)) return "remoteDisabled";