diff --git a/docs/site/content/docs/notifications.mdx b/docs/site/content/docs/notifications.mdx index 8d5e02866f7..e3aa8da76c4 100644 --- a/docs/site/content/docs/notifications.mdx +++ b/docs/site/content/docs/notifications.mdx @@ -29,3 +29,24 @@ Pick a custom desktop notification sound per category under [Settings → Notifi Supported formats: MP3, WAV, OGG, M4A, AAC, FLAC. One file applies to all delivered desktop notifications. When you use a custom sound, set its playback volume from the same settings pane. + +## Disable mobile push from a host + +Set `ORCA_MOBILE_PUSH_MODE` in the environment of each desktop or remote runtime +that sends mobile push, then restart that host: + +- `full` (default): existing notification titles, bodies and navigation identifiers. +- `disabled`: no alert or test sends and no new push registration from that host. + Existing registration deletion and queued cleanup still run. This does not + itself erase historical gateway/provider records or disable live in-app events. + +An unrecognized nonempty value disables push delivery. This is a host configuration, +not a centrally enforced organization policy. Users who control the host environment +can change it. It applies to that host's push gateway traffic, not local desktop +notifications or direct/Relay application content. Every sending host needs the +setting; older Orca versions do not implement it. OS notification permissions and +lock-screen preview settings are separate controls. + +There is no generic-content mode: enabled push may include project/agent text and +identifiers. Disabling phone lock-screen previews does not stop that content from +reaching the push gateway and APNs/FCM. diff --git a/src/main/runtime/push/desktop-push-service.test.ts b/src/main/runtime/push/desktop-push-service.test.ts index 9a0e2297b54..8765477c57c 100644 --- a/src/main/runtime/push/desktop-push-service.test.ts +++ b/src/main/runtime/push/desktop-push-service.test.ts @@ -1,7 +1,7 @@ import { mkdtempSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { describe, expect, it, vi } from 'vitest' +import { afterEach, describe, expect, it, vi } from 'vitest' import type { MobileNotificationEvent } from './notifications/runtime-mobile-notification-controller' import { DeviceRegistry } from '../rpc/server/pairing/device-registry' import { DesktopPushService } from './desktop-push-service' @@ -30,6 +30,7 @@ function createService( deviceId: string deletes: string[] send: ReturnType + registerDevice: ReturnType dispatch: (event: MobileNotificationEvent) => void retries: { run: () => void; delayMs: number }[] } { @@ -88,6 +89,7 @@ function createService( deviceId: device.deviceId, deletes, send: client.send, + registerDevice: client.registerDevice, dispatch: (event) => listener?.(event), retries } @@ -249,3 +251,71 @@ it('does not claim success for missing registrations or failed gateway sends', a }) await expect(service.test(deviceId)).resolves.toEqual({ accepted: false, reason: 'rate_limited' }) }) + +describe('host mobile push privacy', () => { + afterEach(() => vi.unstubAllEnvs()) + + it('keeps existing content delivery when the host has no privacy override', async () => { + vi.stubEnv('ORCA_MOBILE_PUSH_MODE', undefined) + const h = createService() + try { + await h.service.register({ ...REGISTER_INPUT, deviceId: h.deviceId }) + h.dispatch({ + type: 'notification', + source: 'terminal-bell', + title: 'Private project', + body: 'Agent context', + notificationId: 'project-alert', + notificationSeq: 1, + notificationEpoch: 'epoch' + }) + expect(h.send).toHaveBeenCalledWith({ + registrationIds: ['reg-1'], + notification: expect.objectContaining({ + title: 'Private project', + body: 'Agent context', + notificationId: 'project-alert' + }) + }) + } finally { + h.service.stop() + } + }) + + it.each(['disabled', 'invalid-mode'])( + 'blocks registration and delivery in %s mode while retaining cleanup', + async (mode) => { + vi.stubEnv('ORCA_MOBILE_PUSH_MODE', mode) + const h = createService() + try { + await expect( + h.service.register({ ...REGISTER_INPUT, deviceId: h.deviceId }) + ).resolves.toEqual({ registered: false, reason: 'gateway_rejected' }) + expect(h.registerDevice).not.toHaveBeenCalled() + h.registry.setPushRegistration(h.deviceId, { + registrationId: 'existing-reg', + filter: {}, + expiresAt: Date.now() + 60_000 + }) + h.dispatch({ + type: 'notification', + source: 'terminal-bell', + title: 'Private', + body: 'Context', + notificationSeq: 1, + notificationEpoch: 'epoch' + }) + await expect(h.service.test(h.deviceId)).resolves.toEqual({ + accepted: false, + reason: 'unavailable' + }) + expect(h.send).not.toHaveBeenCalled() + await h.service.unregister(h.deviceId) + await h.service.flushUnregisterOutbox() + expect(h.deletes).toEqual(['existing-reg']) + } finally { + h.service.stop() + } + } + ) +}) diff --git a/src/main/runtime/push/desktop-push-service.ts b/src/main/runtime/push/desktop-push-service.ts index 7b0c7b18a8b..5e89d05e688 100644 --- a/src/main/runtime/push/desktop-push-service.ts +++ b/src/main/runtime/push/desktop-push-service.ts @@ -12,6 +12,10 @@ import type { OrcaRuntimeRpcServer } from '../rpc/server/runtime-rpc' import { PushDispatcher } from './push-dispatcher' import { PushGatewayClient } from './push-gateway-client' import { PushRegisterThrottle } from './push-register-throttle' +import { + readMobilePushDeliveryMode, + type MobilePushDeliveryMode +} from './mobile-push-delivery-policy' import type { PushUnregisterOutbox } from './push-unregister-outbox' const OUTBOX_RETRY_BASE_MS = 30_000 @@ -38,6 +42,7 @@ export class DesktopPushService { private readonly outbox: PushUnregisterOutbox private readonly client: PushGatewayClient private readonly dispatcher: PushDispatcher + private readonly deliveryMode: MobilePushDeliveryMode private readonly registerThrottle: PushRegisterThrottle private readonly scheduleRetry: (run: () => void, delayMs: number) => void private unsubscribe: (() => void) | null = null @@ -58,7 +63,8 @@ export class DesktopPushService { this.registry = registry this.client = client this.outbox = options.runtimeRpc.getPushUnregisterOutbox() - this.dispatcher = new PushDispatcher({ client, registry }) + this.deliveryMode = readMobilePushDeliveryMode() + this.dispatcher = new PushDispatcher({ client, registry, deliveryMode: this.deliveryMode }) this.registerThrottle = options.registerThrottle ?? new PushRegisterThrottle() this.scheduleRetry = options.scheduleRetry ?? @@ -110,7 +116,7 @@ export class DesktopPushService { if (device?.scope !== 'mobile' || !registration || registration.expiresAt <= Date.now()) { return { accepted: false, reason: 'not_registered' } } - if (this.stopped) { + if (this.stopped || this.deliveryMode === 'disabled') { return { accepted: false, reason: 'unavailable' } } // Explicit tests target only the caller and bypass automatic activity filters. @@ -152,6 +158,9 @@ export class DesktopPushService { } async register(input: MobilePushRegisterInput): Promise { + if (this.deliveryMode === 'disabled') { + return { registered: false, reason: 'gateway_rejected' } + } if (this.registry.getDevice(input.deviceId)?.scope !== 'mobile') { return { registered: false, reason: 'not_mobile' } } diff --git a/src/main/runtime/push/mobile-push-delivery-policy.ts b/src/main/runtime/push/mobile-push-delivery-policy.ts new file mode 100644 index 00000000000..319ab5f54b9 --- /dev/null +++ b/src/main/runtime/push/mobile-push-delivery-policy.ts @@ -0,0 +1,13 @@ +export type MobilePushDeliveryMode = 'full' | 'disabled' + +export function readMobilePushDeliveryMode(): MobilePushDeliveryMode { + const value = process.env.ORCA_MOBILE_PUSH_MODE?.trim().toLowerCase() + if (!value || value === 'full') { + return 'full' + } + if (value === 'disabled') { + return 'disabled' + } + console.warn('[push] Invalid ORCA_MOBILE_PUSH_MODE; push delivery disabled') + return 'disabled' +} diff --git a/src/main/runtime/push/push-dispatcher.ts b/src/main/runtime/push/push-dispatcher.ts index b8ef5c16cd6..2af9ad98fe8 100644 --- a/src/main/runtime/push/push-dispatcher.ts +++ b/src/main/runtime/push/push-dispatcher.ts @@ -5,6 +5,7 @@ import { allowsMobilePushDelivery, mobilePushAlertContent } from '../../../share import type { MobileNotificationEvent } from './notifications/runtime-mobile-notification-controller' import type { PushGatewayClient, PushSendNotification } from './push-gateway-client' import { PushOutcomeCounters } from './push-outcome-counters' +import type { MobilePushDeliveryMode } from './mobile-push-delivery-policy' const PUSH_RETRY_DELAY_MS = 2_000 // Split requests at the gateway's per-send limit so extra paired phones still receive notifications. @@ -18,6 +19,7 @@ export type PushDispatcherRegistry = { type PushDispatcherOptions = { client: PushGatewayClient registry: PushDispatcherRegistry + deliveryMode?: MobilePushDeliveryMode /** Test seam: lets a suite drive the single retry without real time. */ scheduleRetry?: (run: () => void, delayMs: number) => void } @@ -30,11 +32,13 @@ export class PushDispatcher { private stopped = false private readonly client: PushGatewayClient private readonly registry: PushDispatcherRegistry + private readonly deliveryMode: MobilePushDeliveryMode private readonly scheduleRetry: (run: () => void, delayMs: number) => void constructor(options: PushDispatcherOptions) { this.client = options.client this.registry = options.registry + this.deliveryMode = options.deliveryMode ?? 'full' this.scheduleRetry = options.scheduleRetry ?? ((run, delayMs) => { @@ -53,7 +57,7 @@ export class PushDispatcher { } enqueue(event: MobileNotificationEvent): void { - if (this.stopped) { + if (this.stopped || this.deliveryMode === 'disabled') { return } try {