Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 5 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
- Replace the `global.forceDefaultOpsPtc` switch with one explicit action: the row's detail page carries a **Make OPS (PTC) the default** button that writes `selectedDefault: ops-ptc` once and answers `applied`/`no-update`/`unavailable`/`failed`. Apply, remount and unload no longer write the default, so a preset chosen on the settings page is not overridden on the next apply, and a saved `global.forceDefaultOpsPtc` key still loads with no effect.
- 用一次显式操作取代 `global.forceDefaultOpsPtc` 开关:行详情页有一个「设为 OPS (PTC) 默认」按钮,点一次写 `selectedDefault: ops-ptc`,并回报 `applied`/`no-update`/`unavailable`/`failed`。apply、重挂载与卸载都不再改写默认,设置页选定的预设不会在下一次 apply 被覆盖;已保存的 `global.forceDefaultOpsPtc` 键仍可加载但不再生效。

- Paths through an Electron `.asar` archive now fail with the explicit `ARCHIVE_MEMBER_UNSUPPORTED` diagnosis: only Electron's patched in-process filesystem presents the archive as a directory, so the standalone worker cannot read its members. This is an actionable diagnostic, not a virtual-filesystem fallback (#836).
- 穿过 Electron `.asar` 的路径现在明确返回 `ARCHIVE_MEMBER_UNSUPPORTED`:只有 Electron 进程内经补丁的文件系统会把归档呈现为目录,独立 worker 无法读取成员。这是可操作的诊断,不是虚拟文件系统回退(#836)。
- Windows mutations capture, restore and byte-verify every user-restorable extended attribute. `$KERNEL.*` names are reported individually in `metadataWarnings` because user mode cannot recreate them; every other capture/restore/verification failure still aborts publication instead of silently dropping metadata (#874).
- Windows 写入现在捕获、恢复并逐字节核验所有用户态可恢复的扩展属性。`$KERNEL.*` 名称因用户态无法重建而逐名写入 `metadataWarnings`;其他任何捕获、恢复或核验失败仍会中止发布,不会静默丢弃元数据(#874)。

## [0.5.5] — 2026-11-13 — Patch release

- A loader-less PTC scope no longer registers the configured `allowedTools` pool: with dynamic loading off nothing could ever select those APIs, and a host assembly without a step tool set declared all sixteen in `tools:sdk`. Resident publication, the default inspect + loader set and selection behavior are unchanged (#887).
Expand Down
4 changes: 3 additions & 1 deletion docs/file-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ These are the current contracts, including deliberate differences between tools.

Revision computation for `stat`, `copy`, `move` and `remove` streams SHA-256 instead of loading the whole file, so those operations accept files over 32 MiB. Hex inspection streams whole-file facts without buffering them, then seeks to and buffers only its requested window. Whole-content text inspection, `diff` and mutation buffers retain their explicit content budgets.

On Windows volumes without named-stream or ACL support, mutations preserve available basic metadata and return `metadataWarnings` instead of `METADATA_UNSUPPORTED`. Windows source metadata that is present but unsupported, such as NTFS alternate data streams, still fails closed.
On Windows volumes without named-stream or ACL support, mutations preserve available basic metadata and return `metadataWarnings` instead of `METADATA_UNSUPPORTED`. On NTFS, user-restorable extended attributes are captured, restored and byte-verified. `$KERNEL.*` names are listed individually in `metadataWarnings` because user mode cannot recreate them; any other EA capture, restore or verification failure fails closed. Unsupported source metadata such as NTFS alternate data streams also fails closed.

A path through an Electron `.asar` file returns `ARCHIVE_MEMBER_UNSUPPORTED`. Electron presents that archive as a directory only inside its own patched process filesystem; the standalone worker sees a regular file and cannot read archive members. Inspect the archive itself in hex view or use an unpacked copy.

`replace` is not bound to an earlier `inspect_local_file` result. Use `edit_file` when a single-file change must depend on that exact read. A `replace` preview is not a reservation: execution rescans. `changed` counts applied literal replacements, not files. A preview has `dryRun: true`; planned hashes alone do not establish that writes happened. Directory replacement records permission-denied reads in `skippedPaths` and returns `complete: false` with `truncated: true` while continuing eligible neighbors; ordinary binary-file skips do not by themselves make the result incomplete. Update-lock, staging and publication denials still fail the call, and sharing violations or other IO failures retain their structured error instead of becoming skips.

Expand Down
4 changes: 3 additions & 1 deletion docs/文件读写契约.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ English: [File read and mutation contracts](file-contracts.md).

`stat`、`copy`、`move` 与 `remove` 以流式 SHA-256 计算 revision,不再整读文件,因此可处理超过 32 MiB 的文件。hex 检查会在不缓冲完整内容的情况下流式计算整文件事实,随后只定位并缓冲请求窗口。需要完整内容的文本检查、`diff` 与写入缓冲仍保留各自明确的内容预算。

在不支持命名流或 ACL 的 Windows 卷上,写入会保留可用的基本元数据并返回 `metadataWarnings`,不再返回 `METADATA_UNSUPPORTED`。Windows 上真实存在但不受支持的源元数据(例如 NTFS 备用数据流)仍会闭锁拒绝。
在不支持命名流或 ACL 的 Windows 卷上,写入会保留可用的基本元数据并返回 `metadataWarnings`,不再返回 `METADATA_UNSUPPORTED`。在 NTFS 上,用户态可恢复的扩展属性会被捕获、恢复并逐字节核验;`$KERNEL.*` 名称因用户态无法重建而逐名写入 `metadataWarnings`。其他任何 EA 捕获、恢复或核验失败都会闭锁拒绝;不受支持的源元数据(例如 NTFS 备用数据流)同样闭锁拒绝。

穿过 Electron `.asar` 文件的路径会返回 `ARCHIVE_MEMBER_UNSUPPORTED`。只有 Electron 进程内经补丁的文件系统会把归档呈现为目录,独立 worker 看到的仍是普通文件,无法读取归档成员。请用 hex 视图检查归档本身,或改用解包后的副本。

`replace` 不绑定之前 `inspect_local_file` 的读取结果。单文件变更必须依赖该次读取时使用 `edit_file`。replace 预览不会预留文件,执行时重新扫描。`changed` 是已应用字面替换次数,不是文件数。预览带 `dryRun: true`,仅有计划 hash 不能证明已经写入。目录替换遇到读取权限拒绝时会记录 `skippedPaths`,返回 `complete: false` 与 `truncated: true`,并继续处理其他合格文件;普通的二进制文件跳过本身不会使结果不完整。更新锁、暂存与发布阶段的权限拒绝仍使调用失败,共享冲突及其他 IO 故障也保留结构化错误,不会改记为跳过。

Expand Down
29 changes: 28 additions & 1 deletion native/crates/ops-files/src/file_path.rs
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,27 @@ pub fn checked_leaf(raw: &str, allow_missing: bool) -> Result<Target> {
let mut parent = Dir::open_ambient_dir(&anchor, ambient_authority())?;
let name = names.pop().unwrap_or_else(|| ".".into());
for component in names {
regular(&parent.symlink_metadata(&component)?, true)?;
let metadata = parent.symlink_metadata(&component)?;
if regular(&metadata, true).is_err()
&& metadata.is_file()
&& asar_archive(&component)
{
// #836: Electron presents .asar archives as directories only through
// its own patched in-process filesystem. The standalone worker sees
// a regular file, so a member path can never resolve; name the
// archive instead of implying a no-follow bypass.
return Err(Failure::new(
"ARCHIVE_MEMBER_UNSUPPORTED",
format!(
"Path routes inside '{component}': an Electron .asar archive is a \
virtual directory only for its host process; this standalone \
worker cannot read archive members. Inspect the archive file \
itself (hex view) or use an unpacked copy; no other tool here \
can open it either."
),
));
}
regular(&metadata, true)?;
parent = parent.open_dir_nofollow(&component)?;
}
regular(&parent.dir_metadata()?, true)?;
Expand Down Expand Up @@ -115,6 +135,13 @@ pub fn validate_name(name: &str) -> Result<()> {
ops_protocol::windows_paths::validate_name(name)?;
Ok(())
}
/// Electron's asar archive spelling: a regular file whose name ends in ".asar".
/// A directory with the same spelling stays an ordinary directory.
fn asar_archive(name: &str) -> bool {
let bytes = name.as_bytes();
bytes.len() >= 5 && bytes[bytes.len() - 5..].eq_ignore_ascii_case(b".asar")
}

pub fn link(metadata: &Metadata) -> bool {
if metadata.file_type().is_symlink() {
return true;
Expand Down
43 changes: 43 additions & 0 deletions native/crates/ops-files/src/file_path_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,46 @@ fn near_audit_names_are_not_reserved_components() {
crate::paths::relative(name).unwrap();
}
}

#[test]
fn asar_file_components_are_archive_members_not_traversal_bypasses() {
let root = std::env::temp_dir().join(format!("dsh-ops-asar-{}", uuid::Uuid::new_v4()));
std::fs::create_dir(&root).unwrap();
std::fs::write(root.join("bundle.asar"), b"archive bytes").unwrap();
// #836: Electron presents a real .asar FILE as a directory only through its
// own patched filesystem; the worker names the archive member instead of
// implying a no-follow bypass.
let failure = match checked_leaf(root.join("bundle.asar").join("app.js").to_str().unwrap(), true)
{
Err(failure) => failure,
Ok(_) => panic!("a file component must not become a traversable directory"),
};
assert_eq!(failure.code, "ARCHIVE_MEMBER_UNSUPPORTED");
assert!(failure.message.contains("bundle.asar"), "{}", failure.message);
// A genuine directory keeps working: the .asar spelling is not reserved.
std::fs::create_dir(root.join("folder.asar")).unwrap();
std::fs::write(root.join("folder.asar").join("inner.js"), b"real").unwrap();
let directory = checked_leaf(
root.join("folder.asar").join("inner.js").to_str().unwrap(),
false,
)
.unwrap();
assert_eq!(directory.name, "inner.js");
// A plain file component that is not an archive keeps the traversal refusal.
std::fs::write(root.join("readme.txt"), b"text").unwrap();
let plain = match checked_leaf(
root.join("readme.txt").join("inner.js").to_str().unwrap(),
true,
) {
Err(failure) => failure,
Ok(_) => panic!("a plain file must not become a traversable directory"),
};
assert_eq!(plain.code, "PATH_RESTRICTED");
// The archive itself stays a readable regular file.
let archive = checked_leaf(root.join("bundle.asar").to_str().unwrap(), false).unwrap();
assert_eq!(archive.name, "bundle.asar");
// The Targets hold directory handles on Windows; drop them before removing.
drop(directory);
drop(archive);
std::fs::remove_dir_all(&root).unwrap();
}
Loading
Loading