Skip to content

docs(architecture): audit Sandbox and privacy group against implementation #4800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ggbdpq wants to merge 3 commits into
base: main
Choose a base branch
from
+55 −5
Open

docs(architecture): audit Sandbox and privacy group against implementation #4800

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
835b727
docs(architecture): audit Sandbox and privacy group against implement…
ggbdpq Sep 4, 2026
4c9a102
Merge branch 'main' into docs/audit-sandbox-privacy-a6
ggbdpq Sep 5, 2026
012ca95
docs: record the notification-gate exception to the workspace privacy…
ggbdpq Sep 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/architecture/windows-sandbox-rfc-v1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: architecture.windows-sandbox-rfc-v1
title: "Windows sandbox RFC v1"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: synced
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down
12 changes: 12 additions & 0 deletions docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: architecture.windows-sandbox-rfc-v1
title: "Windows sandbox RFC v1"
language: zh-CN
source_language: en
implementation_status: current
document_status: current
translation_status: synced
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down
12 changes: 12 additions & 0 deletions docs/permission-onboarding-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: permission-onboarding-plan
title: "Drag-to-grant permission onboarding (macOS)"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: source-only
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down
24 changes: 19 additions & 5 deletions docs/workspace-privacy-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: workspace-privacy-context
title: "Workspace privacy context"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: source-only
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down Expand Up @@ -29,21 +41,23 @@ export interface WorkspacePrivacyContext {

## Authority

The main process owns the effective workspace privacy state. Renderers may request a change and display the current value, but a renderer-provided value is never proof of the effective state.
The Runtime Host owns the effective workspace privacy state as runtime policy. Renderers may request a change and display the current value, but a renderer-provided value is never proof of the effective state.

@hqhq1025 hqhq1025 Sep 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Account for the notification gate before declaring one privacy authority

The settings path does write privacy only to Runtime Host policy: apps/desktop/src/main/runtime-host-settings-ipc-main.ts:373-374 calls set_privacy, while apps/desktop/src/shared/settings-ownership.ts:55-64 excludes privacy from the local settings patch. However, apps/desktop/src/main/notifications-ipc-main.ts:57-68 still reads settingsStore.get().privacy.incognitoActive and may display the session title/reply preview from that stale local value. After a user enables incognito, Runtime operations can see true while the notification gate still sees the old/default false. Please fix that consumer to read the Runtime Host authority, or keep this document from claiming the authority migration is complete and record the exception; otherwise the audited privacy contract masks a reachable content-disclosure path.


The current authority path is:

- `apps/desktop/src/renderer/settings/general-settings-page.tsx` requests settings changes.
- `apps/desktop/src/main/main.ts` resolves the effective state through `getWorkspacePrivacyContext()`.
- Main-process consumers receive that resolved context rather than trusting renderer input.
- The effective state is the Runtime Host runtime policy: `packages/core/src/runtime-policy.ts` declares the readonly `privacy.incognitoActive` field and defaults it to `false`; patches are validated by the policy codec's `privacy patch` record rule.
- Desktop surfaces resolve the effective state from the policy via `queryRuntimePolicy()` (for example `apps/desktop/src/main/runtime-host-search-ipc-main.ts`), and core-boundary consumers validate the projected context through `validateWorkspacePrivacyContext()` (`packages/core/src/incognito.ts`) before reading any field.

`defaultWorkspacePrivacyContext()` returns `{ incognitoActive: false }` for explicit initialization. `validateWorkspacePrivacyContext()` rejects malformed input; it never converts missing or invalid data to `false`. Boundaries that cannot resolve a valid authoritative context must fail closed.
One documented exception: the run-ended notification gate (`apps/desktop/src/main/notifications-ipc-main.ts`) still reads `privacy.incognitoActive` from the local settings store, and privacy patches never reach that store (`apps/desktop/src/shared/settings-ownership.ts` excludes `privacy` from the local patch), so the gate keeps seeing the stale or default value after incognito is enabled and can raise a notification carrying the session title and reply preview. Migrating this gate to the policy authority is a named follow-up; until it lands, this gate is the one documented deviation from the rule above.

`validateWorkspacePrivacyContext()` rejects malformed input; it never converts missing or invalid data to `false`. Boundaries that cannot resolve a valid authoritative context must fail closed.

## Consumer rule

`incognitoActive: false` only means that incognito mode did not block the operation. It is not general permission to read, write, search, capture, or transmit data. Every consumer must still apply its own settings, permission, and retention rules.

When `incognitoActive` is true, each privacy-sensitive consumer defines a fail-closed result at its existing main-process boundary. The composition in `apps/desktop/src/main/main.ts` and focused consumer tests own the current inventory. Do not duplicate that inventory here, add another incognito flag, copy the state into a parallel store, or let a renderer self-attest.
When `incognitoActive` is true, each privacy-sensitive consumer defines a fail-closed result at its existing main-process boundary. The Runtime Host composition, the desktop main-process consumers, and their focused tests own the current inventory. Do not duplicate that inventory here, add another incognito flag, copy the state into a parallel store, or let a renderer self-attest.

## Contract changes

Expand Down