Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

feat(policy): enforce the org screen-context policy on desktop (#1581)

Gabriel Stein273b7d64d03b
diff --git a/src/components/settings/DictationAgentSettings.tsx b/src/components/settings/DictationAgentSettings.tsx
index 3f5c3f039..b04a6e39c 100644
--- a/src/components/settings/DictationAgentSettings.tsx
+++ b/src/components/settings/DictationAgentSettings.tsx
@@ -2,7 +2,7 @@ import { useCallback, useState } from "react";
import { useTranslation } from "react-i18next";
import { Monitor } from "lucide-react";
import { useSettingsStore } from "../../stores/settingsStore";
-import { isAgentAllowed } from "../../stores/policyRules";
+import { isAgentAllowed, isScreenContextAllowed } from "../../stores/policyRules";
import { usePolicyStore } from "../../stores/policyStore";
import { useAgentName } from "../../utils/agentName";
import { useDialogs } from "../../hooks/useDialogs";
@@ -33,6 +33,10 @@ export default function DictationAgentSettings() {
request: requestScreenAccess,
} = useScreenRecordingPermission();
const agentAllowed = usePolicyStore(isAgentAllowed);
+ const screenContextAllowed = usePolicyStore(isScreenContextAllowed);
+ // Display the effective value: an org that forces the feature off shows the
+ // toggle off while the raw preference survives for when the policy lifts.
+ const screenContextActive = voiceAgentScreenContext && screenContextAllowed;
const { agentName, setAgentName } = useAgentName();
const [agentNameInput, setAgentNameInput] = useState(agentName);
@@ -173,19 +177,21 @@ export default function DictationAgentSettings() {
<SettingsRow
label={t("dictationAgent.screenContext.enable")}
description={
- screenSupported
- ? t("dictationAgent.screenContext.enableDescription")
- : t("dictationAgent.screenContext.unsupported")
+ !screenContextAllowed
+ ? t("common.managedByOrg")
+ : screenSupported
+ ? t("dictationAgent.screenContext.enableDescription")
+ : t("dictationAgent.screenContext.unsupported")
}
>
<Toggle
- checked={voiceAgentScreenContext}
+ checked={screenContextActive}
onChange={handleScreenContextToggle}
- disabled={!screenSupported}
+ disabled={!screenSupported || !screenContextAllowed}
/>
</SettingsRow>
</SettingsPanelRow>
- {voiceAgentScreenContext && (
+ {screenContextActive && (
<SettingsPanelRow>
<SettingsRow
label={t("dictationAgent.screenContext.visionModel")}
@@ -199,7 +205,7 @@ export default function DictationAgentSettings() {
</SettingsPanelRow>
)}
</SettingsPanel>
- {voiceAgentScreenContext && isMacOS && !screenGranted && (
+ {screenContextActive && isMacOS && !screenGranted && (
<PermissionCard
icon={Monitor}
title={t("dictationAgent.screenContext.permissionTitle")}
@@ -209,12 +215,12 @@ export default function DictationAgentSettings() {
buttonText={t("onboarding.permissions.grantAccess")}
/>
)}
- {voiceAgentScreenContext && isMacOS && screenNeedsRelaunch && (
+ {screenContextActive && isMacOS && screenNeedsRelaunch && (
<p className="text-[11px] text-warning/80 leading-snug">
{t("dictationAgent.screenContext.relaunchHint")}
</p>
)}
- {voiceAgentScreenContext && useDictationAgentVisionModel && (
+ {screenContextActive && useDictationAgentVisionModel && (
<InferenceConfigEditor
scope="dictationAgentVision"
allowedModes={["openwhispr", "providers"]}
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 56b0a4876..2d0f06e9f 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -10,7 +10,10 @@ const { BYOK_API_KEYS } = require("../config/secretKeys");
const tokenStore = require("./tokenStore");
const { createCloudApiRequestHandler } = require("./cloudApiRequest");
const { withPolicyRequestHeaders } = require("./policyRequestHeaders");
-const { createWorkspacePolicyManager } = require("./workspacePolicyManager");
+const {
+ createWorkspacePolicyManager,
+ isScreenContextBlocked,
+} = require("./workspacePolicyManager");
const { createEnterpriseIdentityManager } = require("./enterpriseIdentityManager");
const { createCloudConfigRequestHandler } = require("./cloudConfigRequest");
const {
@@ -4548,7 +4551,39 @@ class IPCHandlers {
ipcMain.handle("open-screen-recording-settings", () => openSystemSettings("screenRecording"));
ipcMain.handle("open-login-items-settings", () => openSystemSettings("loginItems"));
- ipcMain.handle("capture-screen-context", () => screenContextCapture.captureCursorDisplay());
+ ipcMain.handle("capture-screen-context", async (event) => {
+ // Capture immediately so the screenshot reflects the invocation moment;
+ // the policy verdict resolves concurrently and decides whether to
+ // return it. A signed-out user has no workspace and no policy; managed
+ // users are gated even if a stale renderer asks. null matches capture's
+ // contract — a screenshot must never break the dictation it accompanies.
+ const capturePromise = screenContextCapture.captureCursorDisplay();
+ const authHeaders = await getAuthHeader(event);
+ if (authHeaders.Authorization || authHeaders.Cookie) {
+ // Bound the verdict wait: a lapsed policy TTL on a degraded network
+ // must not stall an allowed user's capture past the renderer's 3s
+ // consume race. The renderer gate already fails closed while policy
+ // is unresolved, so this defense-in-depth gate lets an unresolved
+ // verdict through while the refresh completes in flight — a resolved
+ // denial (cached or fresh) still blocks.
+ const snapshot = await Promise.race([
+ workspacePolicyManager.getPolicy({
+ expectedAuthGeneration: tokenStore.getState().generation,
+ authHeaders,
+ }),
+ new Promise((resolve) => setTimeout(() => resolve(null), 1500)),
+ ]);
+ if (snapshot && isScreenContextBlocked(snapshot)) {
+ debugLogger.warn(
+ "Screen context capture blocked by org policy",
+ { code: snapshot.code ?? null },
+ "screenContext"
+ );
+ return null;
+ }
+ }
+ return capturePromise;
+ });
// Snapshot the launch-time TCC status so a mid-session grant (which macOS
// only honors after a relaunch) is detectable even if the renderer never
diff --git a/src/helpers/policyValidation.js b/src/helpers/policyValidation.js
index 418d16c6d..5f9d065c5 100644
--- a/src/helpers/policyValidation.js
+++ b/src/helpers/policyValidation.js
@@ -38,6 +38,9 @@ function isValidPolicyShape(policy) {
isKnownList(policy.llm.allowedEnterpriseProviders, ENTERPRISE_PROVIDERS) &&
typeof policy.features?.agentEnabled === "boolean" &&
typeof policy.features?.webSearchEnabled === "boolean" &&
+ // Additive within policy version 1: absent (older server) means allowed.
+ (policy.features?.screenContextEnabled === undefined ||
+ typeof policy.features.screenContextEnabled === "boolean") &&
SHARING_MODES.includes(policy.sharing?.externalLinkSharing) &&
LOCAL_HISTORY_MODES.includes(policy.dataRetention?.localHistoryMode) &&
typeof policy.dataRetention?.cloudBackupAllowed === "boolean" &&
diff --git a/src/helpers/workspacePolicyManager.js b/src/helpers/workspacePolicyManager.js
index 67574aed8..9eea6b78b 100644
--- a/src/helpers/workspacePolicyManager.js
+++ b/src/helpers/workspacePolicyManager.js
@@ -390,4 +390,17 @@ function createWorkspacePolicyManager({
return { getPolicy };
}
-module.exports = { createWorkspacePolicyManager };
+// Main-process capture gate: block an explicit managed denial or an
+// unresolved managed policy; guests and unmanaged users keep the feature.
+function isScreenContextBlocked(snapshot) {
+ return (
+ snapshot.code === "POLICY_UNRESOLVABLE" ||
+ Boolean(
+ snapshot.success &&
+ snapshot.managed &&
+ snapshot.policy?.features?.screenContextEnabled === false
+ )
+ );
+}
+
+module.exports = { createWorkspacePolicyManager, isScreenContextBlocked };
diff --git a/src/hooks/useAudioRecording.js b/src/hooks/useAudioRecording.js
index 726ade9a6..7e67e4634 100644
--- a/src/hooks/useAudioRecording.js
+++ b/src/hooks/useAudioRecording.js
@@ -7,7 +7,11 @@ import { getSettings } from "../stores/settingsStore";
import { expandSnippets } from "../utils/snippets";
import { getRecordingErrorTitle, getRecordingErrorDescription } from "../utils/recordingErrors";
import { isAccessibilitySkipped } from "../utils/permissions";
-import { isAgentAllowed, isTranscriptionContextAllowed } from "../stores/policyRules";
+import {
+ isAgentAllowed,
+ isScreenContextAllowed,
+ isTranscriptionContextAllowed,
+} from "../stores/policyRules";
import { usePolicyStore } from "../stores/policyStore";
// Maps a failed selection-replacement code to its `selectionEditing.*` toast
@@ -73,7 +77,14 @@ export const useAudioRecording = (toast, options = {}) => {
"reasoning"
);
}
- if (voiceAgentRequested && getSettings().voiceAgentScreenContext) {
+ // getSettings() already reflects a managed policy that forces the
+ // setting off; the predicate additionally fails closed while the
+ // policy is still loading or errored.
+ if (
+ voiceAgentRequested &&
+ getSettings().voiceAgentScreenContext &&
+ isScreenContextAllowed(policyState)
+ ) {
audioManagerRef.current.beginScreenContextCapture();
}
@@ -358,6 +369,11 @@ export const useAudioRecording = (toast, options = {}) => {
// Keep overlay content protection in sync with the screen-context setting
// so the dictation pill stays out of captures (survives window recreation).
window.electronAPI.setScreenContextEnabled?.(getSettings().voiceAgentScreenContext);
+ // A policy refresh can flip the effective screen-context value mid-session;
+ // re-sync overlay content protection when it does.
+ const unsubscribePolicy = usePolicyStore.subscribe(() => {
+ window.electronAPI.setScreenContextEnabled?.(getSettings().voiceAgentScreenContext);
+ });
window.electronAPI.getSttConfig?.().then((config) => {
if (config?.success && audioManagerRef.current) {
audioManagerRef.current.setSttConfig(config);
@@ -443,6 +459,7 @@ export const useAudioRecording = (toast, options = {}) => {
// Cleanup
return () => {
+ unsubscribePolicy();
disposeToggle?.();
disposeVoiceAgentToggle?.();
disposeTranslationToggle?.();
diff --git a/src/stores/policyRules.ts b/src/stores/policyRules.ts
index 155dee6c8..53308cb18 100644
--- a/src/stores/policyRules.ts
+++ b/src/stores/policyRules.ts
@@ -109,6 +109,14 @@ export function isWebSearchAllowed(state: PolicyDecisionSnapshot): boolean {
return managedPolicyDecision(state, (policy) => policy.features.webSearchEnabled);
}
+/**
+ * Whether the voice agent may attach screen context. Servers that predate the
+ * field send none; absent means allowed.
+ */
+export function isScreenContextAllowed(state: PolicyDecisionSnapshot): boolean {
+ return managedPolicyDecision(state, (policy) => policy.features.screenContextEnabled !== false);
+}
+
/** Whether cloud backup/sync is allowed. */
export function isCloudBackupAllowed(state: PolicyDecisionSnapshot): boolean {
return managedPolicyDecision(state, (policy) => policy.dataRetention.cloudBackupAllowed);
diff --git a/src/stores/settingsStore.ts b/src/stores/settingsStore.ts
index 986d890cc..673674c11 100644
--- a/src/stores/settingsStore.ts
+++ b/src/stores/settingsStore.ts
@@ -31,6 +31,7 @@ import { adjustBedrockModelForRegion } from "../utils/bedrockRegions";
import modelRegistryData from "../models/modelRegistryData.json";
import {
getTranscriptionSelection,
+ isScreenContextAllowed,
resolveEffectivePolicySelection,
type PolicyDecisionSnapshot,
type TranscriptionPolicyContext,
@@ -2628,6 +2629,8 @@ export function selectPolicyEffectiveSettings(
const effective = { ...state };
const writable = effective as unknown as Record<string, unknown>;
+ if (!isScreenContextAllowed(policyState)) writable.voiceAgentScreenContext = false;
+
for (const keys of TRANSCRIPTION_CONTEXT_KEYS) {
const rawSelection = getTranscriptionSelection(state, keys.context);
const selection = resolveEffectivePolicySelection(
diff --git a/src/types/policy.ts b/src/types/policy.ts
index 8d93b25f3..aea15ea6f 100644
--- a/src/types/policy.ts
+++ b/src/types/policy.ts
@@ -25,6 +25,8 @@ export interface OrgPolicy {
features: {
agentEnabled: boolean;
webSearchEnabled: boolean;
+ /** Absent on servers that predate the field; absent means allowed. */
+ screenContextEnabled?: boolean;
};
sharing: {
externalLinkSharing: ExternalSharingMode;
diff --git a/test/helpers/policyEffectiveSettings.test.js b/test/helpers/policyEffectiveSettings.test.js
index b334db961..bff81aaa2 100644
--- a/test/helpers/policyEffectiveSettings.test.js
+++ b/test/helpers/policyEffectiveSettings.test.js
@@ -236,3 +236,41 @@ test("Note Recording never inherits an unsupported self-hosted policy fallback",
assert.equal(effective.meetingTranscriptionMode, "local");
assert.equal(effective.meetingUseLocalWhisper, true);
});
+
+test("a managed screen-context denial forces the effective setting off without touching the preference", async (t) => {
+ const browser = installBrowserGlobals(t, {
+ initialStorage: { voiceAgentScreenContext: "true" },
+ });
+ const vite = await createRendererServer(t, {
+ cachePrefix: "openwhispr-policy-screen-context-test-",
+ });
+ const { usePolicyStore } = await vite.ssrLoadModule("/stores/policyStore.ts");
+ const { getSettings, useSettingsStore } = await vite.ssrLoadModule("/stores/settingsStore.ts");
+
+ usePolicyStore.setState({
+ status: "managed",
+ managed: true,
+ policy: {
+ ...managedPolicy,
+ features: { ...managedPolicy.features, screenContextEnabled: false },
+ },
+ appVersion: "1.8.1",
+ });
+
+ assert.equal(getSettings().voiceAgentScreenContext, false);
+ // The raw preference survives the policy for when it lifts.
+ assert.equal(useSettingsStore.getState().voiceAgentScreenContext, true);
+ assert.equal(browser.storage.getItem("voiceAgentScreenContext"), "true");
+
+ // A policy that omits the field (older server) leaves the setting alone.
+ usePolicyStore.setState({
+ status: "managed",
+ managed: true,
+ policy: managedPolicy,
+ appVersion: "1.8.1",
+ });
+ assert.equal(getSettings().voiceAgentScreenContext, true);
+
+ usePolicyStore.setState({ status: "unmanaged", managed: false, policy: null });
+ assert.equal(getSettings().voiceAgentScreenContext, true);
+});
diff --git a/test/helpers/policyRules.test.js b/test/helpers/policyRules.test.js
index 255ad2155..43db9e748 100644
--- a/test/helpers/policyRules.test.js
+++ b/test/helpers/policyRules.test.js
@@ -661,6 +661,42 @@ test("active control-panel views reroute on their specific policy capability", a
assert.equal(isControlPanelViewAllowed("home", false, false), true);
});
+test("screen context is allowed unless a managed policy turns it off", async () => {
+ const { isScreenContextAllowed } = await load();
+
+ assert.equal(isScreenContextAllowed({ status: "idle", policy: null, appVersion: null }), true);
+ assert.equal(
+ isScreenContextAllowed({ status: "unmanaged", policy: null, appVersion: null }),
+ true
+ );
+ // Fail closed while the managed verdict is unknown.
+ assert.equal(
+ isScreenContextAllowed({ status: "loading", policy: null, appVersion: null }),
+ false
+ );
+ assert.equal(isScreenContextAllowed({ status: "error", policy: null, appVersion: null }), false);
+
+ // The shared fixture omits the field — the old-server contract: allowed.
+ assert.equal(isScreenContextAllowed({ status: "managed", policy, appVersion: null }), true);
+ const withFlag = (screenContextEnabled) => ({
+ status: "managed",
+ policy: { ...policy, features: { ...policy.features, screenContextEnabled } },
+ appVersion: null,
+ });
+ assert.equal(isScreenContextAllowed(withFlag(true)), true);
+ assert.equal(isScreenContextAllowed(withFlag(false)), false);
+
+ // An org-required update denies everything, screen context included.
+ assert.equal(
+ isScreenContextAllowed({
+ status: "managed",
+ policy: { ...policy, minAppVersion: "9.9.9" },
+ appVersion: "1.8.1",
+ }),
+ false
+ );
+});
+
test("cloud-backup resume fires only on a denial-to-grant transition", async () => {
const { cloudBackupResumed } = await load();
const unmanaged = { status: "unmanaged", policy: null, appVersion: null };
diff --git a/test/helpers/policyValidation.test.js b/test/helpers/policyValidation.test.js
index 6b7c00404..f23520e9f 100644
--- a/test/helpers/policyValidation.test.js
+++ b/test/helpers/policyValidation.test.js
@@ -46,6 +46,25 @@ test("ignores stale additive analytics metadata", () => {
assert.equal(isValidPolicyShape(policy), true);
});
+test("accepts screenContextEnabled as an optional boolean", () => {
+ for (const value of [true, false]) {
+ const policy = validPolicy();
+ policy.features.screenContextEnabled = value;
+ assert.equal(isValidPolicyShape(policy), true, String(value));
+ }
+
+ // Servers that predate the field omit it — the old-server contract.
+ assert.equal(isValidPolicyShape(validPolicy()), true);
+});
+
+test("rejects a malformed screenContextEnabled", () => {
+ for (const value of [null, "off", 1]) {
+ const policy = validPolicy();
+ policy.features.screenContextEnabled = value;
+ assert.equal(isValidPolicyShape(policy), false, String(value));
+ }
+});
+
test("requires the supported policy schema version", () => {
for (const version of [undefined, null, 0, 2, "1"]) {
const policy = validPolicy();
diff --git a/test/helpers/workspacePolicyManager.test.js b/test/helpers/workspacePolicyManager.test.js
index 7f33b66ab..6a800b247 100644
--- a/test/helpers/workspacePolicyManager.test.js
+++ b/test/helpers/workspacePolicyManager.test.js
@@ -4,7 +4,10 @@ const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
-const { createWorkspacePolicyManager } = require("../../src/helpers/workspacePolicyManager");
+const {
+ createWorkspacePolicyManager,
+ isScreenContextBlocked,
+} = require("../../src/helpers/workspacePolicyManager");
const validPolicy = (updatedAt = "2026-08-05T00:00:00.000Z") => ({
data: {
@@ -814,3 +817,50 @@ test("throttled errors carry the snapshot identity fields", async (t) => {
assert.equal(throttled.accountId, "account-a");
assert.equal(throttled.authGeneration, 1);
});
+
+test("screen-context capture blocks on managed denial or an unresolved managed policy", async (t) => {
+ const denyingPolicy = () => {
+ const body = validPolicy();
+ body.data.policy.features.screenContextEnabled = false;
+ return body;
+ };
+ let body = denyingPolicy();
+ const context = setup(async () => response(200, body));
+ t.after(context.cleanup);
+ const request = { accountId: "account-a", expectedAuthGeneration: 1 };
+
+ assert.equal(isScreenContextBlocked(await context.manager.getPolicy(request)), true);
+
+ // Explicitly enabled, and absent (a server that predates the field): allowed.
+ body = validPolicy();
+ body.data.policy.features.screenContextEnabled = true;
+ assert.equal(isScreenContextBlocked(await context.manager.getPolicy(request)), false);
+ body = validPolicy();
+ assert.equal(isScreenContextBlocked(await context.manager.getPolicy(request)), false);
+});
+
+test("screen-context capture stays available to unmanaged users and plain outages", async (t) => {
+ let online = true;
+ const context = setup(async () => {
+ if (!online) throw new Error("offline");
+ return response(200, { data: { managed: false, policy: null, policyUpdatedAt: null } });
+ });
+ t.after(context.cleanup);
+ const request = { accountId: "account-a", expectedAuthGeneration: 1 };
+
+ assert.equal(isScreenContextBlocked(await context.manager.getPolicy(request)), false);
+
+ // A transient failure with an unmanaged cache is not a managed denial.
+ online = false;
+ assert.equal(isScreenContextBlocked(await context.manager.getPolicy(request)), false);
+});
+
+test("screen-context capture fails closed while a managed policy is unresolvable", async (t) => {
+ const context = setup(async () => response(503, { code: "POLICY_UNRESOLVABLE" }));
+ t.after(context.cleanup);
+ const request = { accountId: "account-a", expectedAuthGeneration: 1 };
+
+ const snapshot = await context.manager.getPolicy(request);
+ assert.equal(snapshot.code, "POLICY_UNRESOLVABLE");
+ assert.equal(isScreenContextBlocked(snapshot), true);
+});