You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/10/10 10:56:57 UTC
(maka) branch main updated: docs: verify the sandbox and privacy docs against main (#3522) (#6045)
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git
The following commit(s) were added to refs/heads/main by this push:
new 080304987c docs: verify the sandbox and privacy docs against main (#3522) (#6045)
080304987c is described below
commit 080304987cf12338c0f8da12d8fad41674e63886
Author: BigDataDZ <76...@users.noreply.github.com>
AuthorDate: Sat Oct 10 18:56:52 2026 +0800
docs: verify the sandbox and privacy docs against main (#3522) (#6045)
Part of the #3522 docs-verification campaign (Sandbox and privacy group).
All four documents were checked claim-by-claim against the code; the group
is in good shape and needed only targeted corrections:
- workspace-privacy-context: the cited example file
runtime-host-search-ipc-main.ts was removed by #5531 — replaced with the
live queryRuntimePolicy consumer runtime-host-settings-ipc-main.ts;
last_verified refreshed (content changed via #5742).
- permission-onboarding-plan: the permissions-actions.ts line reference
pointed at a pre-ASF-header line number (now a type-union member); it now
cites the deep-link/openExternal block (lines 61-90).
- windows-sandbox-rfc (EN+ZH): the §6.5 status date corrected to the #3722
merge date (2026-08-25); the "typed unavailable reasons are deferred"
wording now distinguishes the readiness-probe-level collapse from the
transform layer, which already emits unsupported_platform /
backend_not_available / invalid_request; last_verified refreshed.
Refs #3522
Generated-by: ZCode
---
docs/architecture/windows-sandbox-rfc-v1.md | 15 +++++++++------
docs/architecture/windows-sandbox-rfc-v1.zh-CN.md | 14 ++++++++------
docs/permission-onboarding-plan.md | 2 +-
docs/workspace-privacy-context.md | 4 ++--
4 files changed, 20 insertions(+), 15 deletions(-)
diff --git a/docs/architecture/windows-sandbox-rfc-v1.md b/docs/architecture/windows-sandbox-rfc-v1.md
index ee7f52f098..64b9dc7f32 100644
--- a/docs/architecture/windows-sandbox-rfc-v1.md
+++ b/docs/architecture/windows-sandbox-rfc-v1.md
@@ -6,7 +6,7 @@ source_language: en
implementation_status: current
document_status: current
translation_status: synced
-last_verified: 2026-09-04
+last_verified: 2026-10-10
owners:
- maka-backend
---
@@ -242,15 +242,16 @@ Lexical prefix checks are never authorization evidence.
§6.5.)_
- Missing setup, identity drift, ACL-state corruption, ineffective network policy, unsupported
filesystem, helper mismatch, or a failed probe returns a stable typed unavailable reason. _(Later
- gate: the readiness probe today collapses every failure to a single fail-closed boolean surfaced as
- `backend_not_available`; the structured typed reasons are deferred — see §6.5.)_
+ gate: the readiness probe today collapses every probe failure to a single fail-closed boolean surfaced as
+ `backend_not_available`; richer probe-level typed reasons are deferred — the transform layer already
+ distinguishes `unsupported_platform`, `backend_not_available`, and `invalid_request`. See §6.5.)_
- `auto` and `require` never fall back to host execution for a restricted managed profile.
- Diagnostics expose the backend, setup version, and failure stage without paths, SIDs, credentials,
environment values, or firewall details. _(Later gate: the probe runs with `stdio: 'ignore'` and
retains only the exit result, so setup version and failure stage are not yet propagated — deferred
with the structured unavailable reasons, see §6.5.)_
-### 6.5 Preview implementation status (2026-08-24)
+### 6.5 Preview implementation status (2026-08-25)
The first product slice — the packaged Windows 11 x64 AppContainer backend in
[#2961](https://github.com/apache/maka/pull/2961), merged 2026-08-17 — enforces a subset
@@ -337,8 +338,10 @@ Designed but deferred as later gates (not enforced in the preview slice):
recomputed and enforced in-broker on every launch; verifying the launcher binary's Authenticode
signature and version against packaged metadata is deferred together with Phase 3 signing.
- Structured unavailable reasons and diagnostics (§6.4). The readiness probe fails closed as a single
- boolean surfaced as `backend_not_available`; the stable typed unavailable reasons and the
- setup-version/failure-stage diagnostics are designed but not yet implemented or propagated.
+ boolean surfaced as `backend_not_available`; richer probe-level typed reasons and the
+ setup-version/failure-stage diagnostics are designed but not yet implemented or propagated. (The
+ transform layer already distinguishes `unsupported_platform`, `backend_not_available`, and
+ `invalid_request`.)
- Concurrent real-machine readiness race coverage (§6.4). The readiness profile lifecycle is
serialized by a named mutex and covered by unit tests over the mutex-name, namespace, and
validation primitives; a multi-process race test that spawns real concurrent probes on a live
diff --git a/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md b/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
index b7ef54ea35..58b67f308b 100644
--- a/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
+++ b/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
@@ -6,7 +6,7 @@ source_language: en
implementation_status: current
document_status: current
translation_status: synced
-last_verified: 2026-09-04
+last_verified: 2026-10-10
owners:
- maka-backend
---
@@ -169,12 +169,13 @@ Maka 外已失陷的同用户进程。sandboxed code 从第一条指令开始按
- readiness probe 的抛弃式 profile 生命周期必须隔离且 fail closed； _(已实现:probe profile 位于专属 `maka.readiness.` 命名空间,与生产 `maka.sandbox.` 命名空间结构性不相交,其保留的 `requestId` 被 launch validation 拒绝,任何生产启动都无法解析到 probe 删除并重建的那个 profile;整个 delete→create→probe→settle→drop 生命周期由一个 DACL 加固的按用户命名互斥量跨进程串行——与 ACL ledger 复用同一原语——使并发 probe 不会互删对方的 active 注册;当 probe 无法证明其 Job 清空时按该周期 fail closed(报告不可用),固定的 readiness identity 并不被持久隔离——清理依赖 kill-on-close Job 的整树终止,且因该 probe 不授任何 filesystem root,一个假设存活的子进程也继承不到任何 ACE 权限;消费侧对负可 [...]
- launcher signature/version/digest 必须与 package metadata 一致； _(后续门禁：每次启动的 request digest 目前已在 broker 内重算并强制；对照打包 metadata 校验 launcher 二进制的 signature 与 version 随 Phase 3 签名一并暂缓 —— 见 §6.5。)_
- setup 缺失、identity drift、ACL state 损坏、网络策略无效、文件系统不支持、helper 不匹配、probe 失败都返回
- stable typed unavailable reason； _(后续门禁:readiness probe 目前把每种失败收敛为单一 fail-closed 布尔,统一以
- `backend_not_available` 呈现;结构化 typed reason 尚未实现,暂缓 —— 见 §6.5。)_
+ stable typed unavailable reason； _(后续门禁:readiness probe 目前把每种 probe 失败收敛为单一 fail-closed 布尔,统一以
+ `backend_not_available` 呈现;更细的 probe 层 typed reason 暂缓 —— transform 层已区分
+ `unsupported_platform`、`backend_not_available`、`invalid_request`。见 §6.5。)_
- restricted managed profile 在 `auto`/`require` 下绝不 fallback host execution；
- diagnostics 只暴露 backend、setup version 与 failure stage，不暴露 path、SID、credential、env 或 firewall detail。 _(后续门禁:probe 以 `stdio: 'ignore'` 运行且只保留退出结果,setup version 与 failure stage 尚未传播,与结构化 unavailable reason 一并暂缓 —— 见 §6.5。)_
-### 6.5 预览实现状态（2026-08-24）
+### 6.5 预览实现状态（2026-08-25）
首个预览切片 [#2961](https://github.com/apache/maka/pull/2961) 已于 2026-08-17 合并，强制上述保证的一个子集。本节把文档与已交付代码对齐，使 RFC 不 overclaim：§6.3/§6.4 中尚未强制的保证在此显式标为后续门禁。标注 `(#3722)` 的条目（Runtime Host 父进程 wait handle、64 次 soak、恶意 child 矩阵）与标注 `(#3174)` 的条目（readiness probe 与 private desktop 放置）落在对应后续 PR，而非已合并的 #2961 切片；其余未标注条目由 #2961 当前强制。
@@ -206,8 +207,9 @@ Maka 外已失陷的同用户进程。sandboxed code 从第一条指令开始按
- readiness 阶段的完整策略覆盖（§6.4):readiness probe 已建立生产 AppContainer identity/token、kill-on-close Job 与 private desktop 并在其上启动受限子进程,但尚未在 readiness 阶段编译并演练按 profile 的精确 filesystem 根与 offline network 策略 —— 这些目前按每次启动强制,而非在 readiness 阶段复证;
- 随 Phase 3 签名一并落地的 launcher signature/version 校验（§6.4）。
- 结构化 unavailable reason 与 diagnostics（§6.4）:readiness probe 以单一 fail-closed 布尔(呈现为
- `backend_not_available`)收敛所有失败;stable typed unavailable reason 与 setup-version/failure-stage
- 诊断已设计但尚未实现或传播。
+ `backend_not_available`)收敛所有 probe 失败;更细的 probe 层 typed reason 与 setup-version/failure-stage
+ 诊断已设计但尚未实现或传播。（transform 层已区分 `unsupported_platform`、`backend_not_available`、
+ `invalid_request`。）
- readiness 的跨进程并发真机竞态覆盖（§6.4）:readiness profile 生命周期已由命名互斥量串行,并有针对
互斥量名、命名空间与 validation 原语的单元测试;在真实 Windows 宿主上 spawn 多个并发 probe 的多进程
竞态测试暂缓——对一个抛弃式诊断探针不成比例且在 CI 中天然 flaky。被强制的契约是串行化原语本身,而非
diff --git a/docs/permission-onboarding-plan.md b/docs/permission-onboarding-plan.md
index 2876fba36b..dc78a35535 100644
--- a/docs/permission-onboarding-plan.md
+++ b/docs/permission-onboarding-plan.md
@@ -47,7 +47,7 @@ Six steps, and the file picker is where most people give up.
maka today does the honest-but-minimal thing: `permissions-actions.ts`
deep-links into the right pane and stops there
-(`apps/desktop/src/main/permissions-actions.ts:52`). Everything after the
+(`apps/desktop/src/main/permissions-actions.ts:61-90`). Everything after the
deep link is on the user.
Apple's design intent is that the user *explicitly* adds the app — that
diff --git a/docs/workspace-privacy-context.md b/docs/workspace-privacy-context.md
index e08b6f0ca7..3b209595f4 100644
--- a/docs/workspace-privacy-context.md
+++ b/docs/workspace-privacy-context.md
@@ -6,7 +6,7 @@ source_language: en
implementation_status: current
document_status: current
translation_status: source-only
-last_verified: 2026-09-04
+last_verified: 2026-10-10
owners:
- maka-backend
---
@@ -47,7 +47,7 @@ The current authority path is:
- `apps/desktop/src/renderer/settings/general-settings-page.tsx` requests settings changes.
- 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.
+- Desktop surfaces resolve the effective state from the policy via `queryRuntimePolicy()` (for example `apps/desktop/src/main/runtime-host-settings-ipc-main.ts`), and core-boundary consumers validate the projected context through `validateWorkspacePrivacyContext()` (`packages/core/src/incognito.ts`) before reading any field.
Runtime Host omits notification attention from Session catalog changes while its privacy policy is active or cannot be read. Desktop does not use the local settings store to decide Host privacy.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org