From 0426e42d64721068b988af924dac7cb24768e7dd Mon Sep 17 00:00:00 2001 From: James Chapman Date: Fri, 13 Nov 2026 23:31:19 +0000 Subject: [PATCH 01/17] feat: bound run disk growth by sampling writable roots Every trusted run now has --max-disk-mib (default 8192) and records max_disk_bytes. The supervisor measures allocated bytes and file lengths under the confinement's writable roots before the run and once a second on a separate thread, with a final measurement after the tree is empty. Passing either budget ends the whole tree and records limit_exceeded with disk. Measurement fails closed on unreadable roots and oversized trees. The run journal gains max_disk_bytes and peak_disk_bytes; both are optional on replay so 0.18 journals still load, but 0.18 cannot read 0.19 journals. See ADR-0033. Co-Authored-By: Claude Code --- AGENTS.md | 6 +- CHANGELOG.md | 20 + Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 42 +- README.md | 3 +- crates/omgcode-cli/src/run_cli.rs | 29 +- crates/omgcode-cli/tests/run_workflow.rs | 48 ++ crates/omgcode-core/src/run.rs | 21 +- crates/omgcode-core/src/run_journal.rs | 12 + crates/omgcode-core/src/run_journal/tests.rs | 33 + crates/omgcode-platform/src/process.rs | 109 +++- crates/omgcode-platform/src/process/disk.rs | 593 ++++++++++++++++++ crates/omgcode-platform/src/process/linux.rs | 14 +- .../src/process/linux/cgroup.rs | 1 + crates/omgcode-platform/src/process/tests.rs | 69 +- .../src/process/tests/confinement.rs | 39 +- .../src/process/tests/tree_limits.rs | 26 +- .../src/process/tests/windows_confinement.rs | 31 +- .../omgcode-platform/src/process/windows.rs | 15 +- docs/README.md | 4 +- ...-with-job-objects-and-delegated-cgroups.md | 3 +- ...-disk-growth-by-sampling-writable-roots.md | 125 ++++ docs/adr/index.md | 1 + docs/development-tools.md | 12 +- docs/development.md | 8 +- docs/execution.md | 100 ++- docs/platform-support.md | 2 +- docs/security-coding-rules.md | 7 + docs/testing-standards.md | 8 +- 30 files changed, 1290 insertions(+), 99 deletions(-) create mode 100644 crates/omgcode-platform/src/process/disk.rs create mode 100644 docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md diff --git a/AGENTS.md b/AGENTS.md index 792ec2c..5c42b83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,8 +15,10 @@ trusted CLI `run` command starts one program for a workspace whose `execute` preference is enabled. It uses an operator-declared toolchain profile, records intent and outcome in a run journal, and applies Landlock and a seccomp socket filter on Linux or a per-workspace AppContainer on Windows. It never falls back -to the unconfined runner. Every run has tree-wide memory, process, and CPU-time -limits; on Linux the CLI must run in a delegated cgroup v2. Trusted CLI commands record, apply, and revoke +to the unconfined runner. Every run has tree-wide memory, process-count, +CPU-time, and sampled net disk-growth limits; on Linux the CLI must run in a +delegated cgroup v2. The disk limit measures writable roots and is not a +filesystem quota. Trusted CLI commands record, apply, and revoke Windows container ACL grants. Follow the [execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. The core validates replacement records and can prepare protected checkpoints on diff --git a/CHANGELOG.md b/CHANGELOG.md index b3680ad..f86eae0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,26 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.19.0 bounds each trusted run's net disk growth. See ADR-0033. + - **Flag:** `--max-disk-mib` (16 to 1048576, default 8192) is required for + every trusted run. A run without a disk limit is refused before anything + is recorded. + - **Enforcement:** the supervisor measures allocated bytes and file lengths + under the confinement's writable roots before the program starts and once + a second on a separate thread. Each total has its own budget; passing + either ends the whole tree and records `limit_exceeded` with `disk`. A + final measurement runs after the tree is empty. The limit is sampled; it + is not a filesystem quota. + - **Fail closed:** a baseline that cannot be measured records `not_started`. + An unreadable root, or more than 4,000,000 entries, while the run lives + ends it as `supervision_failed`. Links and reparse points are not + followed. Other writers to the roots count as the run's growth. + - **Records:** `run_started` records `max_disk_bytes`, and the `usage` field + of `run_finished` records `peak_disk_bytes`. A run journal written by + 0.19.0 cannot be read by 0.18.0; 0.19.0 reads 0.18.0 journals. + - **Not counted:** directory entries, inode or MFT use, and filesystem + metadata. A hard-linked file is counted once per name. Tested on Windows + 11 build 26300 and WSL 6.6 only. - Version 0.18.0 adds outbound network access for trusted runs. See ADR-0032. - **Gating:** `omgcode run ... --network` needs the workspace `task_network` preference. Without both, a run has no IP networking, as diff --git a/Cargo.lock b/Cargo.lock index 16de8ce..0b7f678 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -592,7 +592,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.18.0" +version = "0.19.0" dependencies = [ "clap", "directories", @@ -605,7 +605,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.18.0" +version = "0.19.0" dependencies = [ "libc", "omgcode-platform", @@ -621,7 +621,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.18.0" +version = "0.19.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 9324d10..83facfe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.18.0" +version = "0.19.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 21c047c..bd571fa 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -1,6 +1,6 @@ # OMGCode implementation plan -Last verified: 2026-11-11. +Last verified: 2026-11-13. This guide is part of `main` after PR #9. Read it before selecting the next increment. Checkpoint preparation does not mean native replacement exists. @@ -52,10 +52,13 @@ This is a resume guide, not a replacement for the owning contracts in - **PR #25 and PR #26** merged at `4eeb12f`: **Phase C4**, version **0.16.0**, with the trusted CLI `run`, toolchain profiles, the run journal, and the `host_services` preference. -- This branch, `codex/resource-limits`: **Phase C5**, version **0.17.0**, with - tree-wide memory, process, and CPU-time limits for every trusted run, and - fixes for the unaddressed PR #26 review comments. It started from `main` at - `4eeb12f`. +- **PR #27** merged at `ac01a74`: **Phase C5**, version **0.17.0**, with + tree-wide memory, process, and CPU-time limits. +- **PR #29** merged at `4c2a561`: **Phase C6**, version **0.18.0**, with + outbound network access behind `task_network` and `--network`. +- This branch, `codex/disk-limit`: **Phase C7**, version **0.19.0**, with a + sampled net disk-growth limit for every trusted run. It started from `main` + at `4c2a561`. Implemented today: @@ -114,9 +117,15 @@ Implemented today: `archive`; - a `host_services` preference that a run's `--host-services` flag also needs (Linux only); + - `--network` behind the live `task_network` preference; + - memory, process, CPU-time, and sampled net disk-growth limits, recorded in + the run journal; - interrupt-to-cancel handling. - See [ADR-0030](docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md). + See [ADR-0030](docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md), + [ADR-0031](docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md), + [ADR-0032](docs/adr/0032-allow-outbound-network-for-trusted-runs-through-task-network.md), + and [ADR-0033](docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -128,8 +137,9 @@ Not implemented: compaction, and standalone CLI checkpoint preparation. - Model write, process, network, Git, or MCP tools; per-call tool approval; and live provider tool-call qualification. -- Model-callable process execution, disk limits, task and package networking, Git, MCP, runtime skills, memories, desktop/UI panels, - compaction, or caches. Nothing calls the unconfined process runner. +- Model-callable process execution, a network destination allowlist, Git, + MCP, runtime skills, memories, desktop/UI panels, compaction, or caches. + Nothing calls the unconfined process runner. - Subscription/API-key provider profiles beyond the local LM Studio route. ## Resume steps @@ -447,8 +457,8 @@ on Windows, and trusted CLI commands as the first caller. See Java has not run, because no JDK was installed. See [ADR-0030](docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md). -- **C5 (this branch, `codex/resource-limits`):** tree-wide limits for every - trusted run. The user chose: +- **C5 (merged as PR #27):** tree-wide limits for every trusted run. The user + chose: - a delegated cgroup v2 on Linux, with OMGCode started in its own `systemd-run --user --scope -p Delegate=yes` scope; - limits always applied, failing closed where they cannot be; @@ -457,11 +467,19 @@ on Windows, and trusted CLI commands as the first caller. See See [ADR-0031](docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md). +- **C6 (merged as PR #29):** outbound network access behind `task_network` and + `--network`, with resolver and public certificate paths on Linux. See + [ADR-0032](docs/adr/0032-allow-outbound-network-for-trusted-runs-through-task-network.md). +- **C7 (this branch, `codex/disk-limit`):** a sampled net disk-growth limit for + every trusted run. The user chose a disk limit as the next increment. The + supervisor measures the writable roots before the run and once a second on a + separate thread, fails closed when it cannot measure, and records the limit + and peak growth. See + [ADR-0033](docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). Next decisions, not yet scheduled: -- a package-network profile; -- a disk limit; +- a network destination allowlist or package-network profile; - a model-callable command tool with per-call approval. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index 302dfdb..84597f2 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,8 @@ directory grants. > network. On Linux, a run that both the `host_services` preference and its > `--host-services` flag allow can reach the host's Unix-domain sockets, such > as service and credential-agent sockets. Runs have memory, process-count, -> and CPU-time limits but no disk limit. +> CPU-time, and sampled disk-growth limits; the disk limit is not a filesystem +> quota. See [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/crates/omgcode-cli/src/run_cli.rs b/crates/omgcode-cli/src/run_cli.rs index be76b89..8921f31 100644 --- a/crates/omgcode-cli/src/run_cli.rs +++ b/crates/omgcode-cli/src/run_cli.rs @@ -9,8 +9,9 @@ use std::time::Duration; use clap::{Args, Subcommand}; use omgcode_core::policy::WorkspaceId; use omgcode_core::run::{ - self, CancelSignal, DEFAULT_TREE_CPU_TIME, DEFAULT_TREE_MEMORY_BYTES, DEFAULT_TREE_PROCESSES, - MAX_CAPTURE_BYTES, MAX_DEADLINE, MAX_TREE_CPU_TIME, MAX_TREE_MEMORY_BYTES, MAX_TREE_PROCESSES, + self, CancelSignal, DEFAULT_TREE_CPU_TIME, DEFAULT_TREE_DISK_BYTES, DEFAULT_TREE_MEMORY_BYTES, + DEFAULT_TREE_PROCESSES, MAX_CAPTURE_BYTES, MAX_DEADLINE, MAX_TREE_CPU_TIME, + MAX_TREE_DISK_BYTES, MAX_TREE_MEMORY_BYTES, MAX_TREE_PROCESSES, MIN_TREE_DISK_BYTES, MIN_TREE_MEMORY_BYTES, ProcessLimits, RunError, RunRequest, TreeLimits, cancel_on_interrupt, }; use serde_json::json; @@ -46,6 +47,11 @@ pub(crate) struct RunArgs { /// 604800). #[arg(long, default_value_t = DEFAULT_TREE_CPU_TIME.as_secs())] max_cpu_secs: u64, + /// Bytes the run may add to its writable roots, in MiB (16 to 1048576). + /// Allocated bytes and file lengths are bounded separately. Sampled once a + /// second, not a filesystem quota. See ADR-0033. + #[arg(long, default_value_t = DEFAULT_TREE_DISK_BYTES / MIB)] + max_disk_mib: u64, /// Allow host Unix-domain sockets, such as the Docker daemon. Needs the /// workspace `host_services` preference. Refused on Windows. #[arg(long)] @@ -102,7 +108,12 @@ pub(crate) fn run(args: RunArgs, data_root: &Path) -> Result<(), CliError> { "Output limit must be at most 16 MiB", )); } - let tree = tree_limits(args.max_memory_mib, args.max_processes, args.max_cpu_secs)?; + let tree = tree_limits( + args.max_memory_mib, + args.max_processes, + args.max_cpu_secs, + args.max_disk_mib, + )?; let mut command = args.command.into_iter(); let program = command .next() @@ -155,7 +166,12 @@ pub(crate) fn run(args: RunArgs, data_root: &Path) -> Result<(), CliError> { const MIB: u64 = 1024 * 1024; /// Check the tree-limit flags against the runner's ranges. -fn tree_limits(memory_mib: u64, processes: u32, cpu_secs: u64) -> Result { +fn tree_limits( + memory_mib: u64, + processes: u32, + cpu_secs: u64, + disk_mib: u64, +) -> Result { let memory = memory_mib .checked_mul(MIB) .filter(|bytes| (MIN_TREE_MEMORY_BYTES..=MAX_TREE_MEMORY_BYTES).contains(bytes)) @@ -173,10 +189,15 @@ fn tree_limits(memory_mib: u64, processes: u32, cpu_secs: u64) -> Result= 1000); @@ -702,10 +708,50 @@ fn a_tree_limit_ends_the_run_and_is_recorded() { assert_eq!(run["finish"]["result"]["code"], 0); assert_eq!(run["start"]["limits"]["max_processes"], 1024); assert_eq!(run["start"]["limits"]["max_cpu_ms"], 7_200_000); + assert_eq!( + run["start"]["limits"]["max_disk_bytes"], + 8u64 * 1024 * 1024 * 1024 + ); assert!(run["finish"]["usage"].is_object()); scene.close(); } +/// Growth in the writable workspace past the disk limit ends the whole run. +/// The limit is recorded before the program starts, and the outcome reports +/// the measured peak growth. +#[test] +fn a_disk_limit_ends_the_run_and_is_recorded() { + let scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + // The source exists before the run, so the baseline counts it. Copying it + // inside the writable workspace adds bytes the disk limit must see. Both + // commands then wait to be stopped. + let source = scene.workspace.join("growth-source.bin"); + fs::write(&source, vec![0u8; 32 * 1024 * 1024]).expect("growth source"); + #[cfg(target_os = "linux")] + let script = "cp growth-source.bin growth.bin; while :; do :; done"; + #[cfg(windows)] + let script = "copy /b growth-source.bin growth.bin >nul & for /l %i in (1,0,2) do @rem"; + let options = ["--max-disk-mib", "16", "--max-memory-mib", "512"]; + let run = run_json(&scene.run("system", &options, &shell(script))); + assert_eq!( + run["start"]["limits"]["max_disk_bytes"], + 16u64 * 1024 * 1024 + ); + assert_eq!(run["finish"]["result"]["kind"], "limit_exceeded"); + assert_eq!(run["finish"]["result"]["limit"], "disk"); + assert!( + run["finish"]["usage"]["peak_disk_bytes"] + .as_u64() + .expect("disk usage") + >= 16 * 1024 * 1024, + "{run}" + ); + assert_eq!(last_result(&scene)["limit"], "disk"); + assert_eq!(scene.audit()["pending"], Value::Array(Vec::new())); + scene.close(); +} + /// Out-of-range tree limits are refused before anything is recorded. #[test] fn out_of_range_tree_limits_are_refused_before_recording() { @@ -718,6 +764,8 @@ fn out_of_range_tree_limits_are_refused_before_recording() { ["--max-processes", "65537"], ["--max-cpu-secs", "0"], ["--max-cpu-secs", "604801"], + ["--max-disk-mib", "15"], + ["--max-disk-mib", "1048577"], ] { let output = scene.run("system", &options, &shell("exit 0")); assert_error_code(&output, "configuration"); diff --git a/crates/omgcode-core/src/run.rs b/crates/omgcode-core/src/run.rs index 11ab9f7..01d8bd7 100644 --- a/crates/omgcode-core/src/run.rs +++ b/crates/omgcode-core/src/run.rs @@ -38,8 +38,8 @@ use crate::workspace::DirectoryRecord; pub use omgcode_platform::interrupt::{InterruptWatch, cancel_on_interrupt}; pub use omgcode_platform::process::{CancelSignal, ProcessLimits, TreeLimits}; pub use omgcode_platform::process::{ - MAX_CAPTURE_BYTES, MAX_DEADLINE, MAX_TREE_CPU_TIME, MAX_TREE_MEMORY_BYTES, MAX_TREE_PROCESSES, - MIN_TREE_MEMORY_BYTES, + MAX_CAPTURE_BYTES, MAX_DEADLINE, MAX_TREE_CPU_TIME, MAX_TREE_DISK_BYTES, MAX_TREE_MEMORY_BYTES, + MAX_TREE_PROCESSES, MIN_TREE_DISK_BYTES, MIN_TREE_MEMORY_BYTES, }; /// Default tree memory limit for a trusted run: 8 GiB. @@ -48,6 +48,8 @@ pub const DEFAULT_TREE_MEMORY_BYTES: u64 = 8 * 1024 * 1024 * 1024; pub const DEFAULT_TREE_PROCESSES: u32 = 1024; /// Default tree CPU-time limit for a trusted run: two CPU-hours. pub const DEFAULT_TREE_CPU_TIME: Duration = Duration::from_secs(2 * 60 * 60); +/// Default tree disk limit for a trusted run: 8 GiB of growth. +pub const DEFAULT_TREE_DISK_BYTES: u64 = 8 * 1024 * 1024 * 1024; /// How long to wait for another command's hold on the control journal. const CONTROL_WAIT: Duration = Duration::from_secs(10); @@ -711,6 +713,7 @@ fn settle( ResourceLimit::Memory => LimitKind::Memory, ResourceLimit::Processes => LimitKind::Processes, ResourceLimit::CpuTime => LimitKind::CpuTime, + ResourceLimit::Disk => LimitKind::Disk, }, }, }, @@ -721,6 +724,7 @@ fn settle( usage: outcome.usage.map(|usage| UsageRecord { cpu_ms: millis(usage.cpu_time), peak_memory_bytes: usage.peak_memory_bytes, + peak_disk_bytes: usage.peak_disk_bytes, }), }; (finish, Some(outcome), None) @@ -792,6 +796,9 @@ fn prepare( let tree = limits.tree.ok_or(RunError::Refused( "a trusted run needs tree limits; none were given", ))?; + let disk = tree.max_disk_bytes.ok_or(RunError::Refused( + "a trusted run needs a disk limit; none was given", + ))?; let registration = control .workspace(request.workspace_id) .ok_or(ControlError::UnknownWorkspace)?; @@ -874,6 +881,7 @@ fn prepare( max_memory_bytes: tree.max_memory_bytes, max_processes: tree.max_processes, max_cpu_ms: millis(tree.max_cpu_time), + max_disk_bytes: Some(disk), }), network: if request.network { Some(NetworkRecord { @@ -1345,6 +1353,7 @@ mod tests { max_memory_bytes: 1024 * 1024 * 1024, max_processes: 64, max_cpu_time: Duration::from_secs(60), + max_disk_bytes: Some(1024 * 1024 * 1024), }; let cases = [ process::TreeLimits { @@ -1359,6 +1368,14 @@ mod tests { max_cpu_time: Duration::ZERO, ..roomy }, + process::TreeLimits { + max_disk_bytes: Some(1024), + ..roomy + }, + process::TreeLimits { + max_disk_bytes: Some(MAX_TREE_DISK_BYTES + 1), + ..roomy + }, ]; for tree in cases { let request = RunRequest { diff --git a/crates/omgcode-core/src/run_journal.rs b/crates/omgcode-core/src/run_journal.rs index 953f59d..fc7880c 100644 --- a/crates/omgcode-core/src/run_journal.rs +++ b/crates/omgcode-core/src/run_journal.rs @@ -100,6 +100,8 @@ pub enum LimitKind { Processes, /// CPU time summed over the tree. CpuTime, + /// Net allocated-byte growth of the writable roots. + Disk, } /// The tree limits a run started with. @@ -112,6 +114,10 @@ pub struct LimitsRecord { pub max_processes: u32, /// CPU time for the whole tree, in milliseconds. pub max_cpu_ms: u64, + /// Allocated-byte and file-length growth budget for the writable roots, + /// in bytes. Runs recorded by 0.18.0 had no disk limit. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub max_disk_bytes: Option, } /// What a limited tree used. @@ -123,6 +129,11 @@ pub struct UsageRecord { /// Peak memory, when the platform reported it. #[serde(default, skip_serializing_if = "Option::is_none")] pub peak_memory_bytes: Option, + /// Highest net disk growth observed above the pre-run baseline, when a + /// disk limit applied. It is the larger of allocated-byte growth and + /// file-length growth. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub peak_disk_bytes: Option, } /// The network access a run selected. @@ -700,6 +711,7 @@ impl RunJournal { limits.max_memory_bytes == 0 || limits.max_processes == 0 || limits.max_cpu_ms == 0 + || limits.max_disk_bytes == Some(0) }) || start.network.as_ref().is_some_and(|network| { network.support_paths.len() > MAX_NETWORK_SUPPORT_PATHS diff --git a/crates/omgcode-core/src/run_journal/tests.rs b/crates/omgcode-core/src/run_journal/tests.rs index bc87b87..e3242a8 100644 --- a/crates/omgcode-core/src/run_journal/tests.rs +++ b/crates/omgcode-core/src/run_journal/tests.rs @@ -22,6 +22,7 @@ fn start(run_id: Uuid) -> RunStart { max_memory_bytes: 8 << 30, max_processes: 1024, max_cpu_ms: 7_200_000, + max_disk_bytes: Some(8 << 30), }), network: None, } @@ -57,12 +58,15 @@ fn limits_and_usage_are_recorded_and_checked_on_replay() { outcome.usage = Some(UsageRecord { cpu_ms: 40, peak_memory_bytes: Some(1 << 27), + peak_disk_bytes: Some(1 << 24), }); journal.finish(limited, outcome).expect("finish"); drop(journal); let text = fs::read_to_string(directory.path().join(FILE_NAME)).expect("journal text"); assert!(text.contains(r#""kind":"limit_exceeded","limit":"memory""#)); assert!(text.contains(r#""max_cpu_ms":7200000"#)); + assert!(text.contains(r#""max_disk_bytes":8589934592"#)); + assert!(text.contains(r#""peak_disk_bytes":16777216"#)); // The earlier start's line carries no limits field at all. assert_eq!(text.matches("\"limits\"").count(), 1); let journal = RunJournal::open(directory.path(), store).expect("replay"); @@ -79,6 +83,7 @@ fn limits_and_usage_are_recorded_and_checked_on_replay() { not_started.usage = Some(UsageRecord { cpu_ms: 0, peak_memory_bytes: None, + peak_disk_bytes: None, }); let run = Uuid::new_v4(); let entries = [ @@ -93,6 +98,7 @@ fn limits_and_usage_are_recorded_and_checked_on_replay() { max_memory_bytes: 0, max_processes: 1, max_cpu_ms: 1, + max_disk_bytes: Some(1), }); assert!(matches!( RunJournal::apply( @@ -310,6 +316,32 @@ fn entry(store: Uuid, sequence: u64, action: RunAction) -> RunEntry { } } +/// A start or outcome written before 0.19.0 has no disk field. It must +/// deserialize with the default, and a 0.19.0 record must carry the field. +#[test] +fn disk_fields_are_optional_for_pre_0_19_records() { + let mut earlier = start(Uuid::new_v4()); + let limits = earlier.limits.expect("limits"); + earlier.limits = Some(LimitsRecord { + max_disk_bytes: None, + ..limits + }); + let text = serde_json::to_string(&earlier).expect("serialize start"); + assert!(!text.contains("max_disk_bytes"), "{text}"); + let decoded: RunStart = serde_json::from_str(&text).expect("deserialize start"); + assert_eq!(decoded, earlier); + + let usage = UsageRecord { + cpu_ms: 1, + peak_memory_bytes: None, + peak_disk_bytes: None, + }; + let text = serde_json::to_string(&usage).expect("serialize usage"); + assert!(!text.contains("peak_disk_bytes"), "{text}"); + let decoded: UsageRecord = serde_json::from_str(&text).expect("deserialize usage"); + assert_eq!(decoded, usage); +} + /// The largest outcome and acknowledgement fit the reserved budget. #[test] fn outcome_events_fit_their_reserve() { @@ -322,6 +354,7 @@ fn outcome_events_fit_their_reserve() { usage: Some(UsageRecord { cpu_ms: u64::MAX, peak_memory_bytes: Some(u64::MAX), + peak_disk_bytes: Some(u64::MAX), }), }; for action in [ diff --git a/crates/omgcode-platform/src/process.rs b/crates/omgcode-platform/src/process.rs index 69d899b..18421b1 100644 --- a/crates/omgcode-platform/src/process.rs +++ b/crates/omgcode-platform/src/process.rs @@ -2,11 +2,14 @@ //! //! This module starts one program with an explicit environment and supervises //! its whole descendant tree: bounded output, a deadline, cooperative -//! cancellation, and observed tree cleanup. [`run`] applies no filesystem or -//! network confinement. [`run_confined`] adds a Landlock filesystem allowlist -//! and a seccomp socket filter on Linux, and an AppContainer with recorded -//! directory grants on Windows. No CLI command or model tool calls either -//! yet. See `docs/execution.md`, ADR-0027, ADR-0028, and ADR-0029. +//! cancellation, observed tree cleanup, and tree-wide memory, process, CPU-time, +//! and disk limits. [`run`] applies no filesystem or network confinement. +//! [`run_confined`] adds a Landlock filesystem allowlist and a seccomp socket +//! filter on Linux, and an AppContainer with recorded directory grants on +//! Windows. The disk limit samples the bytes allocated under the writable +//! roots on a separate thread; neither platform offers a per-run disk quota. +//! See `docs/execution.md`, ADR-0027, ADR-0028, ADR-0029, ADR-0031, and +//! ADR-0033. use std::ffi::{OsStr, OsString}; use std::fmt; @@ -19,11 +22,14 @@ use std::thread; use std::time::{Duration, Instant}; mod confinement; +mod disk; #[cfg(target_os = "linux")] mod linux; #[cfg(windows)] mod windows; +use disk::DiskMonitor; + #[cfg(test)] mod tests; @@ -53,6 +59,10 @@ pub const MAX_TREE_MEMORY_BYTES: u64 = 1024 * 1024 * 1024 * 1024; pub const MAX_TREE_PROCESSES: u32 = 65_536; /// Largest accepted tree CPU-time limit. pub const MAX_TREE_CPU_TIME: Duration = Duration::from_secs(7 * 24 * 60 * 60); +/// Smallest accepted tree disk limit. +pub const MIN_TREE_DISK_BYTES: u64 = 16 * 1024 * 1024; +/// Largest accepted tree disk limit. +pub const MAX_TREE_DISK_BYTES: u64 = 1024 * 1024 * 1024 * 1024; /// Poll interval for exit, deadline, and cancellation checks. const POLL_INTERVAL: Duration = Duration::from_millis(10); @@ -104,8 +114,9 @@ impl Default for ProcessLimits { /// /// The kernel enforces memory and process counts: on Windows through Job /// Object limits, on Linux through a child of the runner's delegated cgroup -/// v2. The supervisor enforces CPU time by polling the tree's accounting. When -/// any limit is reached, the runner terminates the whole tree and reports +/// v2. The supervisor enforces CPU time by polling the tree's accounting and +/// disk growth by sampling the writable roots. When any limit is reached, the +/// runner terminates the whole tree and reports /// [`Termination::LimitExceeded`]. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct TreeLimits { @@ -117,6 +128,12 @@ pub struct TreeLimits { pub max_processes: u32, /// User and kernel CPU time summed over every process the tree started. pub max_cpu_time: Duration, + /// Greatest net growth the tree may add to its writable roots, measured + /// as allocated bytes and as file lengths; passing either budget ends the + /// run. `None` applies no disk limit; a confined run with a limit must + /// name at least one writable path. This is sampled, not a filesystem + /// quota; see [`run_confined`] and `docs/execution.md`. + pub max_disk_bytes: Option, } impl TreeLimits { @@ -136,6 +153,13 @@ impl TreeLimits { "tree CPU-time limit is out of range", )); } + if let Some(disk) = self.max_disk_bytes + && !(MIN_TREE_DISK_BYTES..=MAX_TREE_DISK_BYTES).contains(&disk) + { + return Err(ProcessError::InvalidLimits( + "tree disk limit is out of range", + )); + } Ok(self) } } @@ -149,6 +173,8 @@ pub enum ResourceLimit { Processes, /// The tree used its CPU time. CpuTime, + /// The tree's writable roots grew past the disk limit. + Disk, } /// Resources a limited tree used, read after it was observed empty. @@ -159,6 +185,10 @@ pub struct TreeUsage { /// Peak memory, when the platform reports it: the Windows job's peak /// commit, or Linux `memory.peak` (Linux 5.19 or later). pub peak_memory_bytes: Option, + /// Highest net growth of the writable roots above the pre-run baseline, + /// when a disk limit applied. It is the larger of allocated-byte growth + /// and file-length growth. + pub peak_disk_bytes: Option, } impl ProcessLimits { @@ -278,6 +308,9 @@ pub enum ProcessError { /// The runner could not observe the tree empty, or its output closed, /// within the cleanup timeout. Processes may remain. CleanupUnconfirmed(&'static str), + /// A disk limit could not be prepared or its sampler could not start. + /// Nothing was started. + DiskMeasurement(io::Error), } impl fmt::Display for ProcessError { @@ -302,6 +335,9 @@ impl fmt::Display for ProcessError { "process tree cleanup was not confirmed: {reason}" ) } + Self::DiskMeasurement(error) => { + write!(formatter, "the disk limit could not be applied: {error}") + } } } } @@ -309,7 +345,10 @@ impl fmt::Display for ProcessError { impl std::error::Error for ProcessError { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { match self { - Self::Spawn(error) | Self::Supervision(error) | Self::Confinement(error) => Some(error), + Self::Spawn(error) + | Self::Supervision(error) + | Self::Confinement(error) + | Self::DiskMeasurement(error) => Some(error), _ => None, } } @@ -327,7 +366,15 @@ pub fn run( ) -> Result { let limits = limits.validate()?; validate_spec(spec)?; - run_native(spec, None, limits, cancel) + if limits + .tree + .is_some_and(|tree| tree.max_disk_bytes.is_some()) + { + return Err(ProcessError::InvalidLimits( + "a disk limit needs a confined run", + )); + } + run_native(spec, None, limits, cancel, None) } /// Start one program under filesystem and network confinement and supervise @@ -353,7 +400,11 @@ pub fn run_confined( let limits = limits.validate()?; validate_spec(spec)?; confinement.validate()?; - run_native(spec, Some(confinement), limits, cancel) + let disk = DiskMonitor::prepare( + Some(confinement), + limits.tree.and_then(|tree| tree.max_disk_bytes), + )?; + run_native(spec, Some(confinement), limits, cancel, disk) } /// Check that [`TreeLimits`] can be applied here, so a caller can refuse a @@ -386,8 +437,9 @@ fn run_native( confinement: Option<&Confinement>, limits: ProcessLimits, cancel: &CancelSignal, + disk: Option, ) -> Result { - linux::run(spec, confinement, limits, cancel) + linux::run(spec, confinement, limits, cancel, disk) } #[cfg(windows)] @@ -396,8 +448,9 @@ fn run_native( confinement: Option<&Confinement>, limits: ProcessLimits, cancel: &CancelSignal, + disk: Option, ) -> Result { - windows::run(spec, confinement, limits, cancel) + windows::run(spec, confinement, limits, cancel, disk) } #[cfg(not(any(target_os = "linux", windows)))] @@ -406,6 +459,7 @@ fn run_native( _confinement: Option<&Confinement>, _limits: ProcessLimits, _cancel: &CancelSignal, + _disk: Option, ) -> Result { Err(ProcessError::Unsupported( "process supervision is implemented only on Linux and Windows", @@ -618,11 +672,12 @@ fn supervise( limits: ProcessLimits, cancel: &CancelSignal, confinement: AppliedConfinement, + mut disk: Option, ) -> Result { - let watched = watch(tree, started, limits.deadline, cancel); + let watched = watch(tree, started, limits.deadline, cancel, disk.as_ref()); // Descendants never outlive the run, including after a normal exit. let stopped = stop_tree(tree, limits.cleanup_timeout); - let termination = match (watched, stopped) { + let mut termination = match (watched, stopped) { (Ok(termination), Ok(())) => termination, (_, Err(error)) => return Err(error), (Err(error), Ok(())) => return Err(ProcessError::Supervision(error)), @@ -632,7 +687,20 @@ fn supervise( // failed release is unconfirmed cleanup and is reported first. let usage = tree.usage(); tree.release()?; - let usage = usage.map_err(ProcessError::Supervision)?; + let mut usage = usage.map_err(ProcessError::Supervision)?; + // The final sample runs after the tree is empty. It catches a program + // that wrote past the limit and exited before the next scheduled sample. + if let Some(disk) = &mut disk { + disk.finish().map_err(ProcessError::Supervision)?; + if disk.exceeded() && !matches!(termination, Termination::LimitExceeded { .. }) { + termination = Termination::LimitExceeded { + limit: ResourceLimit::Disk, + }; + } + if let Some(usage) = &mut usage { + usage.peak_disk_bytes = Some(disk.peak_growth()); + } + } let (stdout, stderr) = capture.finish(Instant::now() + limits.cleanup_timeout)?; Ok(ProcessOutcome { termination, @@ -649,6 +717,7 @@ fn watch( started: Instant, deadline: Duration, cancel: &CancelSignal, + disk: Option<&DiskMonitor>, ) -> io::Result { loop { let exited = tree.try_exit()?; @@ -662,6 +731,16 @@ fn watch( if let Some(limit) = reached { return Ok(Termination::LimitExceeded { limit }); } + // Disk growth is sampled off this thread; checking the result is + // cheap. A measurement error fails the run rather than claiming a + // limit that could not be checked. + if let Some(disk) = disk + && disk.check()? + { + return Ok(Termination::LimitExceeded { + limit: ResourceLimit::Disk, + }); + } if let Some(termination) = exited { return Ok(termination); } diff --git a/crates/omgcode-platform/src/process/disk.rs b/crates/omgcode-platform/src/process/disk.rs new file mode 100644 index 0000000..86f9615 --- /dev/null +++ b/crates/omgcode-platform/src/process/disk.rs @@ -0,0 +1,593 @@ +//! Sampled disk-usage enforcement for a run's writable roots. +//! +//! Neither platform offers a per-process or per-job disk quota that works +//! without administrative setup. Windows Job Objects have no disk limit, and a +//! cgroup v2 has no disk controller. The supervisor therefore measures the +//! bytes under the confinement's writable paths on a separate thread and stops +//! the tree when the measured growth passes the limit. +//! +//! This is a sampled control, not a kernel-enforced quota. A tree can pass the +//! limit between two samples, and the growth is net: bytes the tree removes +//! are subtracted. Two totals are tracked: allocated bytes and file lengths. +//! Each file contributes to both, the limit applies to each separately, and +//! the larger net growth is recorded. Tracking length catches writes that a +//! filesystem has not written back yet; tracking allocation catches a +//! pre-existing sparse file being filled in. Filesystem metadata, directory +//! entries, inode or MFT use, and cluster slack are not counted. See +//! `docs/execution.md`. +//! +//! Measurement fails closed. If the supervisor cannot read part of a writable +//! root, the run ends as a supervision failure rather than claiming a limit it +//! cannot measure. + +use std::fs; +use std::io; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; +use std::sync::{Arc, Mutex, PoisonError}; +use std::thread::{self, JoinHandle}; +use std::time::{Duration, Instant}; + +use super::{Confinement, ProcessError}; + +/// How often the monitor samples the writable roots. +const SAMPLE_INTERVAL: Duration = Duration::from_secs(1); +/// How often it checks for a stop request while waiting to sample. +const STOP_CHECK: Duration = Duration::from_millis(100); +/// Most entries one sample may examine. A larger tree fails closed because the +/// supervisor cannot finish the measurement it started. +const MAX_SAMPLED_ENTRIES: usize = 4_000_000; + +/// Disk usage measured above the run's baseline. +pub(super) struct DiskMonitor { + state: Arc, + thread: Option>, + roots: Vec, + /// File sizes in the writable roots immediately before the program + /// started. + baseline: Baseline, + /// Greatest net growth the run may add. + limit: u64, +} + +#[derive(Default)] +struct DiskState { + stop: AtomicBool, + exceeded: AtomicBool, + /// Highest net growth observed, in bytes. + peak_growth: AtomicU64, + /// The first measurement error, if any. Taken once by the supervisor. + error: Mutex>, +} + +/// Two views of the same files. Allocated bytes catch sparse allocation; +/// file lengths catch writes that a filesystem has not written back yet. The +/// limit applies to each separately, and the larger net growth is recorded. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +struct Baseline { + allocated: u64, + logical: u64, +} + +/// The greatest allocated and logical totals a run may reach. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct Ceiling { + allocated: u64, + logical: u64, +} + +struct Measured { + /// Allocated bytes under the roots. When `exceeded` is set this is a + /// partial count that already passed a ceiling. + allocated: u64, + /// File lengths under the roots, likewise partial when exceeded. + logical: u64, + exceeded: bool, +} + +impl std::fmt::Debug for Measured { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + formatter + .debug_struct("Measured") + .field("allocated", &self.allocated) + .field("logical", &self.logical) + .field("exceeded", &self.exceeded) + .finish() + } +} + +impl DiskMonitor { + /// Measure the writable roots before the program starts. + /// + /// `None` means no disk limit. A limit without a confined run, or without + /// a writable path to measure, is refused before anything is recorded. + pub(super) fn prepare( + confinement: Option<&Confinement>, + limit: Option, + ) -> Result, ProcessError> { + let Some(limit) = limit else { + return Ok(None); + }; + let confinement = confinement.ok_or(ProcessError::InvalidLimits( + "a disk limit needs a confined run", + ))?; + let roots = disk_roots(confinement).map_err(ProcessError::DiskMeasurement)?; + if roots.is_empty() { + return Err(ProcessError::InvalidLimits( + "a disk limit needs at least one writable path", + )); + } + let baseline = measure(&roots, None).map_err(ProcessError::DiskMeasurement)?; + Ok(Some(Self { + state: Arc::new(DiskState::default()), + thread: None, + roots, + baseline: Baseline { + allocated: baseline.allocated, + logical: baseline.logical, + }, + limit, + })) + } + + /// Start sampling. Called before the program starts, so a failure starts + /// nothing. + pub(super) fn start(&mut self) -> Result<(), ProcessError> { + if self.thread.is_some() { + return Ok(()); + } + let state = Arc::clone(&self.state); + let roots = self.roots.clone(); + let baseline = self.baseline; + let ceiling = Ceiling { + allocated: baseline.allocated.saturating_add(self.limit), + logical: baseline.logical.saturating_add(self.limit), + }; + let thread = thread::Builder::new() + .name("omgcode-disk".into()) + .spawn(move || sample_until_stopped(&roots, baseline, ceiling, &state)) + .map_err(ProcessError::DiskMeasurement)?; + self.thread = Some(thread); + Ok(()) + } + + /// Whether a sample has already passed the limit. + /// + /// # Errors + /// + /// Returns the first measurement error. It is taken once; the caller stops + /// the run, so later calls do not need it. + pub(super) fn check(&self) -> io::Result { + if let Some(error) = take_error(&self.state) { + return Err(error); + } + Ok(self.state.exceeded.load(Ordering::SeqCst)) + } + + /// Stop sampling, then take one final measurement while the tree is + /// already stopped. + pub(super) fn finish(&mut self) -> io::Result<()> { + self.stop(); + if let Some(error) = take_error(&self.state) { + return Err(error); + } + let ceiling = Ceiling { + allocated: self.baseline.allocated.saturating_add(self.limit), + logical: self.baseline.logical.saturating_add(self.limit), + }; + let measured = measure(&self.roots, Some(ceiling))?; + self.record(&measured); + Ok(()) + } + + /// Whether any measurement passed the limit. + pub(super) fn exceeded(&self) -> bool { + self.state.exceeded.load(Ordering::SeqCst) + } + + /// Highest net growth observed; zero if nothing was added. + pub(super) fn peak_growth(&self) -> u64 { + self.state.peak_growth.load(Ordering::SeqCst) + } + + fn record(&self, measured: &Measured) { + let growth = measured + .allocated + .saturating_sub(self.baseline.allocated) + .max(measured.logical.saturating_sub(self.baseline.logical)); + self.state.peak_growth.fetch_max(growth, Ordering::SeqCst); + if measured.exceeded { + self.state.exceeded.store(true, Ordering::SeqCst); + } + } + + fn stop(&mut self) { + self.state.stop.store(true, Ordering::SeqCst); + if let Some(thread) = self.thread.take() { + // A sampler panic means the limit was not enforced for part of + // the run. Record it so `finish` fails closed; `check` sees it if + // the panic happens before the program exits. + if thread.join().is_err() { + let mut slot = self + .state + .error + .lock() + .unwrap_or_else(PoisonError::into_inner); + if slot.is_none() { + *slot = Some(io::Error::other("the disk sampler panicked")); + } + } + } + } +} + +impl Drop for DiskMonitor { + fn drop(&mut self) { + // Early returns, including a failed start, must not leave the sampler + // running. It stops within one `STOP_CHECK` interval. + self.stop(); + } +} + +/// Wake every second until a stop is requested, measuring each time. +fn sample_until_stopped( + roots: &[PathBuf], + baseline: Baseline, + ceiling: Ceiling, + state: &DiskState, +) { + loop { + let until = Instant::now() + SAMPLE_INTERVAL; + while Instant::now() < until { + if state.stop.load(Ordering::SeqCst) { + return; + } + thread::sleep(STOP_CHECK); + } + if state.stop.load(Ordering::SeqCst) { + return; + } + match measure(roots, Some(ceiling)) { + Ok(measured) => { + let growth = measured + .allocated + .saturating_sub(baseline.allocated) + .max(measured.logical.saturating_sub(baseline.logical)); + state.peak_growth.fetch_max(growth, Ordering::SeqCst); + if measured.exceeded { + state.exceeded.store(true, Ordering::SeqCst); + return; + } + } + Err(error) => { + // Only the first error matters; the supervisor stops the tree. + let mut slot = state.error.lock().unwrap_or_else(PoisonError::into_inner); + if slot.is_none() { + *slot = Some(error); + } + return; + } + } + } +} + +fn take_error(state: &DiskState) -> Option { + // The lock guards only this `Option`; a poisoned lock leaves it readable. + state + .error + .lock() + .unwrap_or_else(PoisonError::into_inner) + .take() +} + +/// Directories (or files) the confined tree can write. On Windows the +/// container also writes to its own profile folder, which is not listed in +/// `read_write` because it needs no grant. +fn disk_roots(confinement: &Confinement) -> io::Result> { + let mut roots = Vec::new(); + for path in &confinement.read_write { + match fs::symlink_metadata(path) { + Ok(metadata) if metadata.is_dir() || metadata.is_file() => roots.push(path.clone()), + // A character device such as `/dev/null` uses no disk. + Ok(_) => {} + // Confinement setup rejects a missing path with its own error. + Err(_) => {} + } + } + #[cfg(windows)] + if let Some(container) = &confinement.container { + // A missing profile is reported by confinement setup with its own + // error; measure the workspace meanwhile. + if let Ok(folder) = crate::container::profile_folder(container) + && folder.is_dir() + { + roots.push(folder); + } + } + // A root inside another root would be counted twice. + let mut outer: Vec = Vec::new(); + for root in roots { + if outer.iter().any(|existing| root.starts_with(existing)) { + continue; + } + outer.retain(|existing| !existing.starts_with(&root)); + outer.push(root); + } + Ok(outer) +} + +/// Sum the bytes under `roots`, stopping once a ceiling is passed. +fn measure(roots: &[PathBuf], ceiling: Option) -> io::Result { + measure_entries(roots, ceiling, MAX_SAMPLED_ENTRIES) +} + +/// [`measure`] with an explicit entry budget, so the fail-closed bound can be +/// tested without creating millions of entries. +fn measure_entries( + roots: &[PathBuf], + ceiling: Option, + max_entries: usize, +) -> io::Result { + let mut allocated = 0u64; + let mut logical = 0u64; + let mut exhausted = false; + let mut examined = 0usize; + let mut pending: Vec = roots.to_vec(); + while let Some(path) = pending.pop() { + examined = examined.saturating_add(1); + if examined > max_entries { + return Err(io::Error::other( + "the writable roots have too many entries to measure for the disk limit", + )); + } + let metadata = match fs::symlink_metadata(&path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == io::ErrorKind::NotFound => continue, + Err(error) => return Err(error), + }; + if is_link_or_reparse(&metadata) { + continue; + } + let file_type = metadata.file_type(); + if file_type.is_dir() { + let entries = match fs::read_dir(&path) { + Ok(entries) => entries, + Err(error) if error.kind() == io::ErrorKind::NotFound => continue, + Err(error) => return Err(error), + }; + for entry in entries { + match entry { + Ok(entry) => pending.push(entry.path()), + Err(error) if error.kind() == io::ErrorKind::NotFound => {} + Err(error) => return Err(error), + } + } + } else if file_type.is_file() { + let (file_allocated, file_logical) = file_sizes(&path, &metadata)?; + allocated = allocated.saturating_add(file_allocated); + logical = logical.saturating_add(file_logical); + if ceiling + .is_some_and(|ceiling| allocated > ceiling.allocated || logical > ceiling.logical) + { + exhausted = true; + break; + } + } + } + Ok(Measured { + allocated, + logical, + exceeded: exhausted, + }) +} + +/// A symbolic link or another reparse point is not followed, so a link inside +/// a writable root cannot make the measurement read outside it or loop. +#[cfg(windows)] +fn is_link_or_reparse(metadata: &fs::Metadata) -> bool { + use std::os::windows::fs::MetadataExt; + + const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0400; + metadata.file_type().is_symlink() + || metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 +} + +#[cfg(not(windows))] +fn is_link_or_reparse(metadata: &fs::Metadata) -> bool { + metadata.file_type().is_symlink() +} + +/// The allocated and logical byte counts for a regular file. The limits apply +/// to each separately: allocation catches a sparse file being filled in, and +/// length catches writes that a filesystem has not written back yet. +#[cfg(target_os = "linux")] +fn file_sizes(_path: &Path, metadata: &fs::Metadata) -> io::Result<(u64, u64)> { + use std::os::unix::fs::MetadataExt; + + // `st_blocks` counts 512-byte units. + Ok((metadata.blocks().saturating_mul(512), metadata.len())) +} + +/// The allocated and logical byte counts for a regular file. See the Linux +/// variant for why both are tracked. +#[cfg(windows)] +#[allow(unsafe_code)] +fn file_sizes(path: &Path, metadata: &fs::Metadata) -> io::Result<(u64, u64)> { + use std::os::windows::ffi::OsStrExt; + use windows_sys::Win32::Foundation::{GetLastError, SetLastError}; + use windows_sys::Win32::Storage::FileSystem::{GetCompressedFileSizeW, INVALID_FILE_SIZE}; + + // Use a verbatim path so long workspace paths are measured rather than + // failing the Win32 normalization limit. + let mut wide: Vec = Vec::new(); + if !path.as_os_str().to_string_lossy().starts_with(r"\\?\") { + wide.extend(r"\\?\".encode_utf16()); + } + wide.extend(path.as_os_str().encode_wide()); + wide.push(0); + let mut high = 0u32; + // SAFETY: each call takes only value arguments; `wide` is a + // NUL-terminated path that outlives the size call and `high` is writable + // storage for the upper size word. `SetLastError` clears the calling + // thread's error so a real size whose low word is all ones is not + // mistaken for a failure. + let low = unsafe { + SetLastError(0); + GetCompressedFileSizeW(wide.as_ptr(), &mut high) + }; + if low == INVALID_FILE_SIZE { + // SAFETY: `GetLastError` reads the calling thread's last-error value + // and touches no other state. + let error = unsafe { GetLastError() }; + if error != 0 { + return Err(io::Error::from_raw_os_error( + i32::try_from(error).unwrap_or(i32::MAX), + )); + } + } + let allocated = (u64::from(high) << 32) | u64::from(low); + Ok((allocated, metadata.len())) +} + +#[cfg(not(any(target_os = "linux", windows)))] +fn file_sizes(_path: &Path, metadata: &fs::Metadata) -> io::Result<(u64, u64)> { + Ok((metadata.len(), metadata.len())) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::io::Write; + + fn write_file(directory: &Path, name: &str, bytes: usize) -> PathBuf { + let path = directory.join(name); + let mut file = fs::File::create(&path).expect("create file"); + file.write_all(&vec![b'x'; bytes]).expect("write file"); + file.sync_all().expect("sync file"); + path + } + + #[test] + fn measurement_counts_regular_files_under_roots() { + let directory = tempfile::tempdir().expect("temporary directory"); + let nested = directory.path().join("nested"); + fs::create_dir(&nested).expect("nested directory"); + write_file(directory.path(), "one.txt", 4096); + write_file(&nested, "two.txt", 8192); + let measured = measure(&[directory.path().to_path_buf()], None).expect("measure"); + assert!(!measured.exceeded); + assert!( + measured.allocated >= 12 * 1024 && measured.logical >= 12 * 1024, + "{measured:?}" + ); + } + + #[test] + fn measurement_stops_once_the_ceiling_is_passed() { + let directory = tempfile::tempdir().expect("temporary directory"); + write_file(directory.path(), "one.txt", 64 * 1024); + let measured = measure( + &[directory.path().to_path_buf()], + Some(Ceiling { + allocated: 1, + logical: 1, + }), + ) + .expect("measure past the ceiling"); + assert!(measured.exceeded); + assert!( + measured.allocated > 1 && measured.logical > 1, + "{measured:?}" + ); + } + + #[test] + fn measurement_skips_links_and_missing_entries() { + let directory = tempfile::tempdir().expect("temporary directory"); + write_file(directory.path(), "one.txt", 4096); + let missing = directory.path().join("gone.txt"); + #[cfg(unix)] + { + std::os::unix::fs::symlink(directory.path(), directory.path().join("loop")) + .expect("symbolic link"); + let measured = measure(&[directory.path().to_path_buf()], None).expect("measure"); + assert!(!measured.exceeded); + assert!( + measured.allocated >= 4096 && measured.logical >= 4096, + "{measured:?}" + ); + } + // A root that disappears measures nothing rather than failing. + let measured = measure(&[missing], None).expect("measure a missing root"); + assert_eq!(measured.allocated, 0); + assert_eq!(measured.logical, 0); + } + + #[test] + fn the_monitor_detects_growth_from_its_thread() { + let directory = tempfile::tempdir().expect("temporary directory"); + let confinement = Confinement { + read_write: vec![directory.path().to_path_buf()], + ..Confinement::default() + }; + let mut monitor = DiskMonitor::prepare(Some(&confinement), Some(16 * 1024 * 1024)) + .expect("prepare") + .expect("a disk limit"); + monitor.start().expect("start"); + write_file(directory.path(), "growth.bin", 64 * 1024 * 1024); + let until = Instant::now() + Duration::from_secs(5); + while Instant::now() < until && !monitor.check().expect("check") { + thread::sleep(Duration::from_millis(50)); + } + assert!(monitor.check().expect("check"), "the growth was not seen"); + monitor.finish().expect("finish"); + assert!(monitor.exceeded()); + assert!(monitor.peak_growth() >= 16 * 1024 * 1024); + } + + #[test] + fn measurement_fails_closed_past_the_entry_budget() { + let directory = tempfile::tempdir().expect("temporary directory"); + write_file(directory.path(), "one.txt", 4096); + let root = directory.path().to_path_buf(); + let error = measure_entries(std::slice::from_ref(&root), None, 1) + .expect_err("the entry budget was exceeded"); + assert!(error.to_string().contains("too many entries"), "{error}"); + } + + #[cfg(unix)] + #[test] + fn an_unreadable_directory_is_an_error() { + use std::os::unix::fs::PermissionsExt; + + let directory = tempfile::tempdir().expect("temporary directory"); + let locked = directory.path().join("locked"); + fs::create_dir(&locked).expect("locked directory"); + write_file(&locked, "one.txt", 4096); + fs::set_permissions(&locked, fs::Permissions::from_mode(0o000)) + .expect("remove permissions"); + let measured = measure(&[directory.path().to_path_buf()], None); + // Restore access before the temporary directory is removed. + fs::set_permissions(&locked, fs::Permissions::from_mode(0o700)) + .expect("restore permissions"); + assert!(measured.is_err(), "an unreadable directory was measured"); + } + + #[test] + fn nested_roots_are_counted_once() { + let directory = tempfile::tempdir().expect("temporary directory"); + let nested = directory.path().join("nested"); + fs::create_dir(&nested).expect("nested directory"); + write_file(&nested, "one.txt", 4096); + let confinement = Confinement { + read_write: vec![directory.path().to_path_buf(), nested.clone()], + ..Confinement::default() + }; + let roots = disk_roots(&confinement).expect("roots"); + assert_eq!(roots, vec![directory.path().to_path_buf()]); + let outer = measure(&roots, None).expect("measure the outer root"); + let inner = measure(std::slice::from_ref(&nested), None).expect("measure the nested root"); + assert_eq!(outer.allocated, inner.allocated); + assert_eq!(outer.logical, inner.logical); + } +} diff --git a/crates/omgcode-platform/src/process/linux.rs b/crates/omgcode-platform/src/process/linux.rs index f9c5bcb..e6498db 100644 --- a/crates/omgcode-platform/src/process/linux.rs +++ b/crates/omgcode-platform/src/process/linux.rs @@ -26,9 +26,9 @@ use self::cgroup::RunCgroup; use self::landlock::Ruleset; use self::seccomp::FilterScope; use super::{ - AppliedConfinement, CancelSignal, Capture, Confinement, ProcessError, ProcessLimits, - ProcessOutcome, ProcessSpec, ProcessTree, ResourceLimit, Termination, TreeUsage, stop_tree, - supervise, + AppliedConfinement, CancelSignal, Capture, Confinement, DiskMonitor, ProcessError, + ProcessLimits, ProcessOutcome, ProcessSpec, ProcessTree, ResourceLimit, Termination, TreeUsage, + stop_tree, supervise, }; const SECCOMP_MODE_FILTER: libc::c_ulong = 2; @@ -39,6 +39,7 @@ pub(super) fn run( confinement: Option<&Confinement>, limits: ProcessLimits, cancel: &CancelSignal, + mut disk: Option, ) -> Result { let (filter, ruleset, applied) = match confinement { None => ( @@ -85,6 +86,11 @@ pub(super) fn run( unsafe { command.pre_exec(move || prepare_child(parent, &filter, ruleset_fd, cgroup_fd)); } + // Start sampling before the program exists, so a sampler that cannot start + // starts nothing. + if let Some(disk) = &mut disk { + disk.start()?; + } let spawned = command.spawn(); drop(ruleset); let mut child = spawned.map_err(ProcessError::Spawn)?; @@ -107,7 +113,7 @@ pub(super) fn run( return Err(ProcessError::Supervision(error)); } }; - let result = supervise(&mut tree, capture, started, limits, cancel, applied); + let result = supervise(&mut tree, capture, started, limits, cancel, applied, disk); if !matches!(result, Err(ProcessError::CleanupUnconfirmed(_))) { tree.confirmed = true; } diff --git a/crates/omgcode-platform/src/process/linux/cgroup.rs b/crates/omgcode-platform/src/process/linux/cgroup.rs index cf1603a..24f764f 100644 --- a/crates/omgcode-platform/src/process/linux/cgroup.rs +++ b/crates/omgcode-platform/src/process/linux/cgroup.rs @@ -281,6 +281,7 @@ impl RunCgroup { Ok(TreeUsage { cpu_time: Duration::from_micros(self.cpu_micros()?), peak_memory_bytes, + peak_disk_bytes: None, }) } diff --git a/crates/omgcode-platform/src/process/tests.rs b/crates/omgcode-platform/src/process/tests.rs index 993a073..07837c3 100644 --- a/crates/omgcode-platform/src/process/tests.rs +++ b/crates/omgcode-platform/src/process/tests.rs @@ -14,7 +14,7 @@ use std::time::{Duration, Instant}; use super::{ AppliedConfinement, CancelSignal, Confinement, MAX_CAPTURE_BYTES, MAX_CLEANUP_TIMEOUT, MAX_CONFINEMENT_PATHS, MAX_DEADLINE, ProcessError, ProcessLimits, ProcessSpec, Termination, - run, run_confined, + TreeLimits, run, run_confined, }; #[cfg(target_os = "linux")] @@ -25,6 +25,7 @@ mod windows_confinement; const FIXTURE_ENV: &str = "OMGCODE_PROCESS_FIXTURE"; const RECORD_ENV: &str = "OMGCODE_PROCESS_FIXTURE_RECORD"; +const GROW_PATH_ENV: &str = "OMGCODE_PROCESS_GROW_PATH"; const FIXTURE_NAME: &str = "process::tests::fixture"; const HARNESS_ARGS: [&str; 5] = [ "--exact", @@ -34,6 +35,8 @@ const HARNESS_ARGS: [&str; 5] = [ "-q", ]; const FLOOD_BYTES: usize = 1024 * 1024; +/// Bytes the `grow-disk` fixture writes before it waits to be stopped. +const GROW_BYTES: usize = 64 * 1024 * 1024; /// Child entry point. It does nothing unless the runner selected a mode. #[test] @@ -94,6 +97,7 @@ fn fixture() { "hog-memory" => tree_limits::hog_memory(), "spawn-many" => tree_limits::spawn_many(), "spin" => tree_limits::spin(), + "grow-disk" => grow_disk(), #[cfg(windows)] "nested-job" => tree_limits::nested_job(), #[cfg(target_os = "linux")] @@ -117,6 +121,20 @@ fn write_record(text: &str) { fs::rename(&temporary, &path).expect("publish record"); } +/// Write allocated bytes to the path named by `GROW_PATH_ENV`, sync them, and +/// wait to be stopped. The sync makes the allocation visible to the sampler. +fn grow_disk() -> i32 { + let path = PathBuf::from(env::var_os(GROW_PATH_ENV).expect("growth path")); + let chunk = vec![b'x'; 1024 * 1024]; + let mut file = fs::File::create(&path).expect("create growth file"); + for _ in 0..GROW_BYTES / chunk.len() { + file.write_all(&chunk).expect("write growth file"); + } + file.sync_all().expect("sync growth file"); + thread::sleep(Duration::from_secs(120)); + 0 +} + /// Start a grandchild that tries to leave the tree, wait for its record, exit. #[allow( clippy::zombie_processes, @@ -196,10 +214,59 @@ fn limits() -> ProcessLimits { } } +/// Limits that apply a disk bound to an otherwise roomy tree. +fn disk_limits(bytes: u64) -> ProcessLimits { + ProcessLimits { + deadline: Duration::from_secs(30), + tree: Some(TreeLimits { + max_memory_bytes: 1024 * 1024 * 1024, + max_processes: 128, + max_cpu_time: Duration::from_secs(60), + max_disk_bytes: Some(bytes), + }), + ..ProcessLimits::default() + } +} + +/// Select the fixture mode that writes allocated bytes to `path`, then waits. +fn grow_spec(mut spec: ProcessSpec, path: &Path) -> ProcessSpec { + spec.environment.retain(|(name, _)| name != FIXTURE_ENV); + spec.environment + .push((OsString::from(FIXTURE_ENV), OsString::from("grow-disk"))); + spec.environment + .push((OsString::from(GROW_PATH_ENV), path.as_os_str().to_owned())); + spec +} + fn text(bytes: &[u8]) -> String { String::from_utf8_lossy(bytes).into_owned() } +/// Marks a test process that already runs in its own delegated scope. +#[cfg(target_os = "linux")] +const DELEGATED_ENV: &str = "OMGCODE_DELEGATED_TEST"; + +/// Run `body` where tree limits can apply. On Linux, limits need a delegated +/// cgroup; unless this process already runs in one, the test re-runs itself +/// under `systemd-run --user --scope -p Delegate=yes`. It needs a user service +/// manager, and a missing manager fails the test rather than skipping it. +fn in_limit_scope(test: &str, body: impl FnOnce()) { + #[cfg(target_os = "linux")] + if env::var_os(DELEGATED_ENV).is_none() { + let status = Command::new("systemd-run") + .args(["--user", "--scope", "--quiet", "-p", "Delegate=yes", "--"]) + .arg(env::current_exe().expect("test executable")) + .args(["--exact", test, "--nocapture", "--test-threads=1", "-q"]) + .env(DELEGATED_ENV, "1") + .status() + .expect("start systemd-run; tree-limit tests need a user service manager"); + assert!(status.success(), "{test} failed in its delegated scope"); + return; + } + let _ = test; + body(); +} + #[test] fn exit_code_and_both_streams_are_captured() { let outcome = run(&spec("echo"), &limits(), &CancelSignal::new()).expect("run fixture"); diff --git a/crates/omgcode-platform/src/process/tests/confinement.rs b/crates/omgcode-platform/src/process/tests/confinement.rs index 6d7c441..5b3e030 100644 --- a/crates/omgcode-platform/src/process/tests/confinement.rs +++ b/crates/omgcode-platform/src/process/tests/confinement.rs @@ -17,9 +17,11 @@ use std::time::Duration; use super::super::{ AppliedConfinement, CancelSignal, Confinement, NetworkAccess, ProcessError, ProcessSpec, - Termination, UnixSocketAccess, network_support_paths, run_confined, + ResourceLimit, Termination, UnixSocketAccess, network_support_paths, run_confined, +}; +use super::{ + FIXTURE_ENV, HARNESS_ARGS, disk_limits, grow_spec, in_limit_scope, limits, spec, text, }; -use super::{FIXTURE_ENV, HARNESS_ARGS, limits, spec, text}; const READ_ONLY_FILE: &str = "OMGCODE_PROBE_READ_ONLY_FILE"; const SECRET_FILE: &str = "OMGCODE_PROBE_SECRET_FILE"; @@ -620,6 +622,39 @@ fn a_networked_run_reaches_the_internet() { assert_results(&allowed, &[("internet-connect", "ok")]); } +/// Growth in the writable workspace past the disk limit ends the whole +/// confined tree, and the outcome reports the measured peak. +#[test] +fn the_disk_limit_ends_a_confined_run() { + in_limit_scope( + "process::tests::confinement::the_disk_limit_ends_a_confined_run", + || { + let scene = Scene::new(); + let growth = scene.workspace.join("growth.bin"); + let spec = grow_spec(scene.spec(), &growth); + let confinement = scene.confinement(UnixSocketAccess::PairsOnly, NetworkAccess::Denied); + let outcome = run_confined( + &spec, + &confinement, + &disk_limits(16 * 1024 * 1024), + &CancelSignal::new(), + ) + .expect("confined run"); + assert_eq!( + outcome.termination, + Termination::LimitExceeded { + limit: ResourceLimit::Disk + } + ); + let usage = outcome.usage.expect("a limited run reports usage"); + assert!( + usage.peak_disk_bytes.expect("disk usage") >= 16 * 1024 * 1024, + "{usage:?}" + ); + }, + ); +} + #[test] fn a_program_outside_the_rules_cannot_start() { let scene = Scene::new(); diff --git a/crates/omgcode-platform/src/process/tests/tree_limits.rs b/crates/omgcode-platform/src/process/tests/tree_limits.rs index a308f36..bcc9d2a 100644 --- a/crates/omgcode-platform/src/process/tests/tree_limits.rs +++ b/crates/omgcode-platform/src/process/tests/tree_limits.rs @@ -10,22 +10,19 @@ use std::process::Command; use std::thread; use std::time::{Duration, Instant}; -use super::{FIXTURE_ENV, HARNESS_ARGS, limits, spec}; +use super::{FIXTURE_ENV, HARNESS_ARGS, in_limit_scope, limits, spec}; use crate::process::{ CancelSignal, ProcessError, ProcessLimits, ResourceLimit, Termination, TreeLimits, check_tree_limits, run, }; -/// Marks a test process that already runs in its own delegated scope. -#[cfg(target_os = "linux")] -const DELEGATED_ENV: &str = "OMGCODE_DELEGATED_TEST"; - /// Generous limits that an ordinary fixture never reaches. fn roomy() -> TreeLimits { TreeLimits { max_memory_bytes: 1024 * 1024 * 1024, max_processes: 256, max_cpu_time: Duration::from_secs(60), + max_disk_bytes: None, } } @@ -36,24 +33,6 @@ fn limited(tree: TreeLimits) -> ProcessLimits { } } -/// Run `body` where tree limits can apply. See the module documentation. -fn in_limit_scope(test: &str, body: impl FnOnce()) { - #[cfg(target_os = "linux")] - if env::var_os(DELEGATED_ENV).is_none() { - let status = Command::new("systemd-run") - .args(["--user", "--scope", "--quiet", "-p", "Delegate=yes", "--"]) - .arg(env::current_exe().expect("test executable")) - .args(["--exact", test, "--nocapture", "--test-threads=1", "-q"]) - .env(DELEGATED_ENV, "1") - .status() - .expect("start systemd-run; tree-limit tests need a user service manager"); - assert!(status.success(), "{test} failed in its delegated scope"); - return; - } - let _ = test; - body(); -} - /// Allocate and touch memory in 1 MiB steps, up to `limit` MiB or the first /// refused allocation, and return what was allocated. Small steps bring a /// Windows job's peak commit close to its limit, as most real breaches do. @@ -91,6 +70,7 @@ pub(super) fn nested_job() -> i32 { max_memory_bytes: 32 * 1024 * 1024, max_processes: 2, max_cpu_time: Duration::from_secs(60), + max_disk_bytes: None, }) .expect("join a nested job"); let held = fill_memory(4096); diff --git a/crates/omgcode-platform/src/process/tests/windows_confinement.rs b/crates/omgcode-platform/src/process/tests/windows_confinement.rs index 601f42e..53384b5 100644 --- a/crates/omgcode-platform/src/process/tests/windows_confinement.rs +++ b/crates/omgcode-platform/src/process/tests/windows_confinement.rs @@ -29,9 +29,9 @@ use windows_sys::Win32::System::Pipes::{ use super::super::{ AppliedConfinement, CancelSignal, Confinement, NetworkAccess, ProcessError, ProcessOutcome, - ProcessSpec, Termination, UnixSocketAccess, run, run_confined, + ProcessSpec, ResourceLimit, Termination, UnixSocketAccess, run, run_confined, }; -use super::{FIXTURE_ENV, HARNESS_ARGS, limits, spec, text}; +use super::{FIXTURE_ENV, HARNESS_ARGS, disk_limits, grow_spec, limits, spec, text}; use crate::container::windows::tests::{TestContainer, identity, unique_name}; use crate::container::{ContainerAccess, grant, revoke}; use crate::private_store::windows::Sid; @@ -355,6 +355,33 @@ fn assert_results(results: &BTreeMap, expected: &[(&str, &str)]) } } +/// Growth in the writable workspace past the disk limit ends the whole +/// contained tree, and the outcome reports the measured peak. +#[test] +fn the_disk_limit_ends_a_confined_run() { + let scene = Scene::new(); + let growth = scene.workspace.join("growth.bin"); + let spec = grow_spec(scene.spec(), &growth); + let outcome = run_confined( + &spec, + &scene.confinement(), + &disk_limits(16 * 1024 * 1024), + &CancelSignal::new(), + ) + .expect("confined run"); + assert_eq!( + outcome.termination, + Termination::LimitExceeded { + limit: ResourceLimit::Disk + } + ); + let usage = outcome.usage.expect("a limited run reports usage"); + assert!( + usage.peak_disk_bytes.expect("disk usage") >= 16 * 1024 * 1024, + "{usage:?}" + ); +} + #[test] fn the_container_reaches_only_granted_paths_and_no_host_service() { let scene = Scene::new(); diff --git a/crates/omgcode-platform/src/process/windows.rs b/crates/omgcode-platform/src/process/windows.rs index b30e8eb..fbfaf6d 100644 --- a/crates/omgcode-platform/src/process/windows.rs +++ b/crates/omgcode-platform/src/process/windows.rs @@ -114,6 +114,7 @@ pub(super) fn run( confinement: Option<&Confinement>, limits: ProcessLimits, cancel: &CancelSignal, + mut disk: Option, ) -> Result { let container = confinement .map(|confinement| prepare_container(spec, confinement)) @@ -135,6 +136,11 @@ pub(super) fn run( .map_err(ProcessError::Spawn)?; let (stdout_read, stdout_write) = pipe().map_err(ProcessError::Spawn)?; let (stderr_read, stderr_write) = pipe().map_err(ProcessError::Spawn)?; + // Start sampling before the program exists, so a sampler that cannot start + // starts nothing. + if let Some(disk) = &mut disk { + disk.start()?; + } let created = { // The lock guards no data, so a poisoned lock carries no broken invariant. @@ -188,7 +194,7 @@ pub(super) fn run( return Err(ProcessError::Supervision(error)); } }; - supervise(&mut tree, capture, started, limits, cancel, applied) + supervise(&mut tree, capture, started, limits, cancel, applied, disk) } /// Check a confinement and derive its container SID before anything starts. @@ -375,6 +381,9 @@ fn job_confirms(job: &OwnedHandle, limits: &JobLimits, limit: ResourceLimit) -> job_peak_memory(job)? >= threshold } ResourceLimit::CpuTime => job_cpu_units(job)? >= limits.max_cpu_units, + // The job has no disk limit; the supervisor samples the writable + // roots instead. A disk result never comes from a job message. + ResourceLimit::Disk => false, }) } @@ -523,6 +532,7 @@ impl ProcessTree for WindowsTree { Ok(Some(TreeUsage { cpu_time: Duration::from_nanos(units.saturating_mul(100)), peak_memory_bytes: Some(job_peak_memory(&self.job)?), + peak_disk_bytes: None, })) } } @@ -1008,6 +1018,7 @@ mod limit_tests { max_memory_bytes: 64 * 1024 * 1024, max_processes: 4, max_cpu_time: Duration::from_secs(60), + max_disk_bytes: None, })) .expect("job"); (job, limits.expect("job limits")) @@ -1087,6 +1098,7 @@ mod limit_tests { max_memory_bytes: 64 * 1024 * 1024, max_processes: 1, max_cpu_time: Duration::from_secs(60), + max_disk_bytes: None, })) .expect("job"); let limits = limits.expect("job limits"); @@ -1120,6 +1132,7 @@ mod limit_tests { std::time::Instant::now(), Duration::from_secs(60), &super::super::CancelSignal::new(), + None, ); drop(tree); // The job's kill-on-close has ended the sleeper. diff --git a/docs/README.md b/docs/README.md index eeb7167..90128b4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -84,7 +84,9 @@ The Rust workflow adds formatting, strict Clippy, unit/integration tests, and separate documentation tests on Windows and Linux. The development guide owns the current commands and limits. There is no frontend yet. The trusted `run` command uses native confinement that was tested on one Windows build and one -Linux kernel only. The limited file broker and the core read/list turn runtime +Linux kernel only. Every trusted run has memory, process-count, CPU-time, and +sampled net disk-growth limits; the disk limit is not a filesystem quota. The +limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed content without writing to the workspace or creating a checkpoint. diff --git a/docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md b/docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md index 85bfdd4..26128d2 100644 --- a/docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md +++ b/docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md @@ -91,7 +91,8 @@ owns the details. limit is then not attributed either. No documented API identifies the job that sent a message, so a nested job's memory message still ends a run that is already within a sixteenth of its own memory limit. -- There is still no disk limit. +- There is still no disk limit. ADR-0033 later added a sampled net disk-growth + limit; that is not a kernel quota. ## References diff --git a/docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md b/docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md new file mode 100644 index 0000000..7684e3e --- /dev/null +++ b/docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md @@ -0,0 +1,125 @@ +# 0033: Bound run disk growth by sampling writable roots + +- Status: Accepted +- Date: 2026-11-13 + +## Context + +Trusted runs have kernel-enforced memory and process limits, polled CPU-time +limits, and, since 0.18.0, optional outbound networking. They had no disk +limit: a confined tree could fill any volume its Landlock or AppContainer rules +let it write. + +No portable per-run disk quota exists for an unprivileged runner. + +- Windows Job Objects expose memory, process, and CPU accounting, but no disk + quota. NTFS per-user quotas need administrative setup on each volume, and the + run's writes are not attributed to a separate user. +- A cgroup v2 has no disk controller. `io.max` limits throughput, not total + bytes. +- Filesystem project quotas need mount options and privileged setup. A tmpfs + size limit needs a mount namespace and is not available to the confined tree + without privileges. +- `RLIMIT_FSIZE` exists on Linux only, limits one file rather than the tree, + and has no Windows equivalent. + +The user selected a disk limit as the next execution increment. It must fail +closed, must not claim a quota the runner cannot enforce, and must keep the +existing rule that every trusted run has all limits. + +## Decision + +Every trusted run records and applies `TreeLimits::max_disk_bytes`. The CLI +flag is `--max-disk-mib` (default 8192, range 16 to 1048576). A trusted run +without a disk limit is refused before it is recorded. + +The supervisor enforces the limit by sampling, not by a filesystem quota: + +- Before the program starts, it measures the allocated bytes and the file + lengths under the confinement's writable paths. Those totals are the + baseline. +- A dedicated `omgcode-disk` thread repeats both measurements once a second + while the run lives. Each total has its own budget of `baseline + limit`; if + either passes, it reports the limit; the supervisor terminates the whole + tree and records `limit_exceeded` with `disk`. +- The final measurement runs after the tree is observed empty, so a program + that wrote past the limit and exited before the next sample still fails. +- The recorded `usage.peak_disk_bytes` is the larger of the two net growths, + each floored at zero. Tracking lengths catches writes before the filesystem + writes back delayed allocation; tracking allocation catches a pre-existing + sparse file being filled in. + +The measured roots are the confinement's `read_write` directories and regular +files, except character devices such as `/dev/null`. On Windows the +container's profile folder (`%LOCALAPPDATA%\Packages\\AC`) is also +measured because the container writes there without a grant. Nested roots are +counted once. + +Measurement is fail-closed. A baseline that cannot be measured records +`not_started`. While the run lives, a root that cannot be read, or more than +4,000,000 entries, ends the run as a supervision failure instead of claiming a +limit that was not measured. Symlinks and other reparse points are not +followed. A first error is reported once and stops the tree. + +The limit is sampled and best-effort in these documented senses: + +- A tree can pass the limit between samples. The overshoot is bounded by the + write rate and the sample interval, not by the kernel. +- Growth is net. Bytes the tree deletes are subtracted, so a tree that deletes + and rewrites the same bytes can churn more than the limit without adding + total use. +- Two totals are measured: allocated bytes and file lengths. The limit applies + to each separately. The measurement reads `st_blocks` on Linux and the + compressed/allocated size on Windows, plus the file length. Directory + entries, inode or MFT records, cluster slack, and filesystem metadata are + not counted. A hard-linked file is counted once per name, so several names + overcount it. +- Other writers to the same roots are counted as the run's growth. An operator + who needs attribution to the run must not allow concurrent writers. +- The sample walks the roots on its own thread. A large workspace makes each + sample slower and adds metadata I/O; it does not block deadline, + cancellation, output, or cleanup checks. + +## Alternatives considered + +- **No disk limit.** Rejected: it leaves the only unstated resource bound in + the execution contract and lets a build fill the host volume. +- **A Windows Job Object limit or cgroup disk controller.** Rejected: neither + exists. +- **NTFS quotas or filesystem project quotas.** Rejected for the prototype: + both need administrative setup, per-volume state, and a separate identity for + the run, none of which the unprivileged runner has. +- **A tmpfs-backed scratch with a size limit.** Rejected: it needs mount + namespace privileges, covers only scratch rather than the workspace, and + would force ordinary workspace writes elsewhere. +- **`RLIMIT_FSIZE`.** Rejected: Linux only, per file rather than per tree, and + it cannot bound many files. +- **Kernel I/O accounting or eBPF.** Rejected for now: privileged setup and a + larger unsafe surface than the sampled supervisor. + +## Consequences + +- The remaining trusted-run resource limit is implemented, and the run journal + records the limit and peak growth. A run journal from 0.19.0 carries + `max_disk_bytes` and `peak_disk_bytes`; 0.18.0 cannot read it, as with + earlier added fields. +- Every trusted run pays one baseline walk and one walk per second. The + baseline walk delays the start; the periodic walk runs beside supervision. +- The limit prevents ordinary runaway build output and large-file copies. It + does not prevent inode or directory-entry exhaustion, and it is not a quota. + The owning guide must keep those limits visible and must not describe the + result as kernel-enforced. +- A run that makes a writable directory unreadable to the supervisor fails as + a supervision error. Landlock does not restrict `chmod`, so this is a + deliberate fail-closed result rather than a bypass. +- Live qualification remains a separate gate. The tests run on Windows 11 + build 26300 and WSL 6.6; they do not qualify other hosts or filesystems. + +## References + +- [Command execution](../execution.md#tree-limits) +- [Development tools](../development-tools.md) +- [Security coding rules](../security-coding-rules.md#process-and-sandbox-boundary) +- [Testing standards](../testing-standards.md) +- [ADR-0031](0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md) +- [ADR-0032](0032-allow-outbound-network-for-trusted-runs-through-task-network.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index efc59a6..1bd688e 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -47,3 +47,4 @@ meaningful alternative does not need an ADR. | [0030: Run trusted commands through recorded toolchain profiles](0030-run-trusted-commands-through-recorded-toolchain-profiles.md) | Accepted | 2026-11-11 | | [0031: Limit whole run trees with job objects and delegated cgroups](0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md) | Accepted | 2026-11-12 | | [0032: Allow outbound network for trusted runs through task_network](0032-allow-outbound-network-for-trusted-runs-through-task-network.md) | Accepted | 2026-11-13 | +| [0033: Bound run disk growth by sampling writable roots](0033-bound-run-disk-growth-by-sampling-writable-roots.md) | Accepted | 2026-11-13 | diff --git a/docs/development-tools.md b/docs/development-tools.md index 87e2f15..ff98c26 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -23,7 +23,8 @@ operator-declared [toolchain profile](execution.md#toolchain-profiles). Version 0.17.0 limits each run's memory, live processes, and CPU time; raise the [tree limits](execution.md#tree-limits) for large builds. On Linux the process limit counts threads, so a parallel compiler needs a higher limit -than its process count. No +than its process count. Version 0.19.0 adds a sampled limit on net disk growth +for the writable roots; it is not a filesystem quota. No model tool runs project tools. Tool support must be qualified on the actual platform; the [execution guide](execution.md#known-limits) lists the toolchains and versions that passed acceptance. @@ -65,9 +66,8 @@ Version 0.16.0 profiles record: - extra variables. The runner owns the scratch and home locations. The run deadline and output -limits are per-run options. Network destinations, loader search paths, -recorded versions, and memory, process-count, and disk limits are not -implemented. +limits are per-run options. Network destinations, loader search paths, and +recorded versions are not implemented. Each selected toolchain profile must eventually define: @@ -174,7 +174,9 @@ The 0.16.0 acceptance tests cover these on both platforms: They are listed in the [execution guide](execution.md#acceptance). Not covered yet: -- disk exhaustion; +- disk exhaustion under concurrent writers, and inode, directory-entry, or + metadata exhaustion; the sampled disk limit is tested with ordinary file + growth; - package downloads through `--network`, and rejection of undeclared destinations, because there is no destination allowlist; - hostile package scripts beyond the hostile programs. diff --git a/docs/development.md b/docs/development.md index 08d70f4..e8622b5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -183,9 +183,11 @@ On Linux a typical profile is `--root /usr --path /usr/bin` plus the toolchain's own root. The run receives only the profile's `PATH` and variables, plus runner-owned home and temporary locations. Output is printed, never stored. `--host-services` also needs `--host-services true` on the -workspace and works only on Linux. `--max-memory-mib`, `--max-processes`, and -`--max-cpu-secs` set the [tree limits](execution.md#tree-limits); the defaults -are 8192 MiB, 1024, and 7200 seconds. The [execution guide](execution.md#trusted-runs) +workspace and works only on Linux. `--max-memory-mib`, `--max-processes`, +`--max-cpu-secs`, and `--max-disk-mib` set the +[tree limits](execution.md#tree-limits); the defaults are 8192 MiB, 1024, 7200 +seconds, and 8192 MiB of net disk growth. The disk limit is sampled, not a +filesystem quota. The [execution guide](execution.md#trusted-runs) owns the checks, the journal, and the known limits, including those for Node on Windows. diff --git a/docs/execution.md b/docs/execution.md index 4ed8c77..a40b909 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -41,6 +41,11 @@ Version 0.18.0 adds [network access](#network-access). A trusted run passes `--network` to get outbound IP networking, and the workspace `task_network` preference must allow it. Runs without the flag keep no IP networking. +Version 0.19.0 adds a sampled [disk-growth limit](#tree-limits). Every trusted +run bounds the allocated bytes it may add to its writable roots. No portable +per-run disk quota exists, so the supervisor measures growth on a separate +thread rather than the kernel enforcing a quota. + ## Accepted decisions The user selected these on 2026-11-11; see @@ -250,6 +255,7 @@ omgcode run --profile [--cwd ] [--max-memory-mib <16-1048576, default 8192>] [--max-processes <1-65536, default 1024>] [--max-cpu-secs <1-604800, default 7200>] + [--max-disk-mib <16-1048576, default 8192>] [--host-services] [--network] -- [arguments...] omgcode runs audit [--limit ] [--archive ] omgcode runs acknowledge @@ -264,6 +270,10 @@ omgcode runs archive --archive-dir - on Linux, `scratch_removed`; - for a `revoked` run, `revoked_because`. +`finish.usage` gives the tree's CPU time and, where the platform reports it, +peak memory. Since 0.19.0 it also gives `peak_disk_bytes`, the highest net +growth of the writable roots above the pre-run baseline. + The command succeeds whenever the run was supervised and its outcome recorded, whatever the program's exit code. Read `run.finish.result`. A failure prints a JSON error with code `run`. @@ -370,19 +380,22 @@ ends. ### Tree limits -The user chose the C5 options on 2026-11-12; see -[ADR-0031](adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md). -Every trusted run has all three limits. There is no unlimited run. +The user chose the C5 options on 2026-11-12 and the C7 option on 2026-11-13; +see [ADR-0031](adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md) +and [ADR-0033](adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). +Every trusted run has all four limits. There is no unlimited run. | Limit | Flag and default | Windows | Linux | | --- | --- | --- | --- | | Memory | `--max-memory-mib`, 8192 | `JobMemoryLimit`: committed private memory of the whole job | `memory.max`, with `memory.swap.max` 0 where swap is accounted and `memory.oom.group` 1 | | Processes | `--max-processes`, 1024 | `ActiveProcessLimit`: processes alive at once | `pids.max`: tasks alive at once, so threads count | | CPU time | `--max-cpu-secs`, 7200 | Job accounting: user plus kernel time of every process the job held | `cpu.stat` `usage_usec` of the run's cgroup | +| Disk growth | `--max-disk-mib`, 8192 | Sampled allocated bytes under the workspace and the container profile folder | Sampled allocated bytes under the workspace and the per-run scratch directory | -The kernel enforces memory and processes. When the tree reaches a limit, the -runner terminates the whole tree and records `limit_exceeded` with the limit, -even if the program then exited by itself: +The kernel enforces memory and processes. The supervisor enforces CPU time by +polling and disk growth by sampling. When the tree reaches a limit, the runner +terminates the whole tree and records `limit_exceeded` with the limit, even if +the program then exited by itself: - **Memory:** on Linux the kernel kills the whole cgroup when it runs out of memory, and the runner sees `oom_kill` in `memory.events`. On Windows an @@ -393,14 +406,22 @@ even if the program then exited by itself: - **CPU time:** the supervisor compares the tree's accounting with the limit at each 10 ms poll. A tree with many busy threads can pass it by up to one poll's worth of CPU time per thread before it is stopped. +- **Disk growth:** the supervisor measures the writable roots before the + program starts and once a second while it runs, on a separate thread. Either + the allocated-byte total or the file-length total passing its baseline plus + the limit ends the tree. A final measurement runs after the tree is empty, + so a short run that wrote past the limit and exited is still recorded as + `limit_exceeded`. See [disk growth](#disk-growth). The report and the `run_finished` record give the tree's CPU time and, where the platform reports it, its peak memory: the job's peak commit on Windows, or -`memory.peak` on Linux 5.19 or later. +`memory.peak` on Linux 5.19 or later. They also give the highest net disk +growth observed above the pre-run baseline. Windows does not guarantee delivery of job messages. If one is lost, the job still enforces the limit, but the run ends as the program decides and is not -recorded as `limit_exceeded`. CPU time does not depend on messages. +recorded as `limit_exceeded`. CPU time and disk growth do not depend on +messages. Windows also sends the limit messages of a job nested in the run's job, such as a tool's own stricter job, to the run's port. So the runner counts a @@ -428,6 +449,45 @@ rather than a normal exit. On Windows 11 build 26300, a nested job's limit messages did not reach the run's port in testing; the check follows the documented behaviour. +#### Disk growth + +No portable per-run disk quota exists for an unprivileged runner: Job Objects +have no disk accounting, a cgroup v2 has no disk controller, and filesystem +quotas need administrative setup. The limit is therefore sampled by the +supervisor; it is not a kernel quota. See +[ADR-0033](adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). + +- **Measured roots:** the confinement's read-write directories and regular + files, except character devices such as `/dev/null`. On Windows the + container profile folder (`%LOCALAPPDATA%\Packages\\AC`) is also + measured, because the container writes there without a grant. A root inside + another root counts once. +- **Baseline and growth:** the allocated-byte and file-length totals are + measured immediately before the program starts. Each budget is that baseline + plus the limit. Deletions reduce the totals, so the recorded + `peak_disk_bytes` is net growth. +- **Allocation and length:** Linux uses `st_blocks * 512` for allocation, + Windows uses the allocated (compressed) size, and both use the file length. + Each file contributes to both totals, and the limit applies to each. Length + catches writes that a filesystem has not written back yet; allocation + catches a pre-existing sparse file being filled in. A sparse file is + therefore counted conservatively at both its length and its allocation. +- **Sampling:** a dedicated thread measures every second. The supervisor + checks its result at the normal 10 ms poll, and a final measurement runs + after the tree is empty. A tree can pass the limit between samples; the + overshoot depends on the write rate. +- **Fail closed:** a baseline that cannot be measured records `not_started`. + An unreadable root or more than 4,000,000 entries while the run lives stops + it as `supervision_failed` rather than claiming a limit that was not + measured. Symlinks and other reparse points are not followed. A run that + makes a writable path unreadable to the supervisor is stopped for the same + reason. +- **Not counted:** directory entries, inode or MFT use, and filesystem + metadata. A hard-linked file is counted once per name, so several names + overcount it. Other writers to the same roots are counted as the run's + growth. A tree that deletes and rewrites the same bytes can churn more than + the limit without adding total use. + #### Linux delegated cgroup Linux needs the runner itself in a cgroup v2 that is delegated to its user. @@ -510,8 +570,8 @@ sequence, a UTC timestamp, and a tagged `action`: | Action | Meaning | | --- | --- | | `created` | Header | -| `run_started` | Synced before the program starts. Records the run ID, workspace, settings revision, profile ID, name, and revision, program path, argument count, `arguments_sha256`, working directory, socket mode, since 0.17.0 `limits` (`max_memory_bytes`, `max_processes`, `max_cpu_ms`), and, since 0.18.0 and only for a networked run, `network` with the `support_paths` it could read (at most 32). | -| `run_finished` | Records the result (`exited`, `signalled`, `deadline_exceeded`, `cancelled`, `revoked`, `limit_exceeded` with its `limit`, `not_started`, `supervision_failed`, or `cleanup_unconfirmed`), the applied confinement, the elapsed time, the output byte counts, and, for a started run, `usage` (`cpu_ms` and, where reported, `peak_memory_bytes`) | +| `run_started` | Synced before the program starts. Records the run ID, workspace, settings revision, profile ID, name, and revision, program path, argument count, `arguments_sha256`, working directory, socket mode, since 0.17.0 `limits` (`max_memory_bytes`, `max_processes`, `max_cpu_ms`, and since 0.19.0 `max_disk_bytes`), and, since 0.18.0 and only for a networked run, `network` with the `support_paths` it could read (at most 32). | +| `run_finished` | Records the result (`exited`, `signalled`, `deadline_exceeded`, `cancelled`, `revoked`, `limit_exceeded` with its `limit`, `not_started`, `supervision_failed`, or `cleanup_unconfirmed`), the applied confinement, the elapsed time, the output byte counts, and, for a started run, `usage` (`cpu_ms`, where reported `peak_memory_bytes`, and since 0.19.0 `peak_disk_bytes`) | | `run_acknowledged` | The operator cleared a pending run | How it works: @@ -528,7 +588,7 @@ How it works: That process holds `/run-owners/.lock` from before the intent is recorded until the outcome is recorded. - **Limits:** at most 16 pending runs; 8 MiB, 4,096 events, and 64 KiB per - event. + event. A journal that records the 0.19.0 fields cannot be read by 0.18.0. - **Reserve:** a new run must leave room for every pending run's remaining events, 1 KiB each: two for a run in progress, one for a run that needs acknowledgement. @@ -552,6 +612,7 @@ tools on both platforms: - host-service selection; - stale profiles; - deadlines, concurrency, and abandoned runs; +- every tree limit, including disk growth; - interrupts, on Linux. `crates/omgcode-cli/tests/toolchain_acceptance.rs` runs real Rust, Python, @@ -763,7 +824,20 @@ These remain true after C6: Linux limits cgroup memory, which includes page cache and kernel memory charged to the tree. Linux counts threads against the process limit. CPU time is checked by polling and can overshoot; see [tree limits](#tree-limits). -- **No disk limit.** A run can fill any volume its rules let it write. +- **Disk growth is sampled, not a quota.** The supervisor measures the + writable roots once a second, so a tree can pass the limit between samples. + Growth is net and applies to allocated bytes and file lengths separately, so + a write is seen before writeback and a sparse file is counted + conservatively. Directory entries, inode or MFT use, and filesystem metadata + are not counted; a hard-linked file is counted once per name. Other writers + are counted as the run's growth. A run that + makes a writable path unreadable to the supervisor, or whose roots hold more + than 4,000,000 entries, fails as `supervision_failed`. See + [disk growth](#disk-growth). +- **Disk-limit coverage.** The limit was tested on Windows 11 build 26300 and + WSL 6.6 only. The tests write 16 MiB or more and observe `limit_exceeded`; + they do not establish behaviour under a full volume, concurrent writers, or + inode exhaustion. - **Linux needs a user service manager.** Every Linux run needs a delegated cgroup, normally a `systemd-run --user` scope. Hosts without a user systemd instance, or with cgroup v1 or a hybrid hierarchy, cannot run. Tree limits @@ -792,12 +866,12 @@ These remain true after C6: | C4 (0.16.0) | Trusted CLI `run` and the `execute` preference | Done: see [trusted runs](#trusted-runs) and ADR-0030 | | C5 (0.17.0) | Tree-wide memory, process, and CPU-time limits | Done: see [tree limits](#tree-limits) and ADR-0031 | | C6 (0.18.0) | Outbound network access behind `task_network` and `--network` | Done: see [network access](#network-access) and ADR-0032 | +| C7 (0.19.0) | Sampled disk-growth limit for every trusted run | Done: see [disk growth](#disk-growth) and ADR-0033 | Later work needs its own decisions: - a network destination allowlist, registry credentials, and development-server networking; -- a disk limit; - a model-callable command tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/platform-support.md b/docs/platform-support.md index cc03ce5..9b9f610 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -21,7 +21,7 @@ containment. | Workspace file broker | Bounded read/list/exclusive-create/single-directory creation through trusted CLI commands; release filesystem support is not qualified | | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | -| Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | +| Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 6efef04..a36b3f0 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -170,6 +170,13 @@ crate. never fall back to an unlimited run when they cannot be applied. On Linux a run cgroup must be joined by the child before `exec`, and limit files must stay outside the confined tree's Landlock rules. +- Give every trusted run a disk-growth limit. The supervisor measures the + confinement's writable roots before the run and while it runs, as allocated + bytes and as file lengths; a failed measurement stops the run rather than + claiming a limit. The disk limit is sampled and is not a kernel or + filesystem quota. Do not describe it as one, and do not count the read-only + roots or host data. A run's recorded limit and peak growth are evidence, not + authority. - Never record argument text, environment values, or output in a journal. Record the argument digest and byte counts. - Treat profile variables as public. Do not add a way to pass credentials diff --git a/docs/testing-standards.md b/docs/testing-standards.md index a4cc3c4..7088d4d 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -39,8 +39,11 @@ system tools. Since 0.17.0, on Linux they start the CLI through `systemd-run --user --scope -p Delegate=yes`, and the platform tree-limit tests rerun themselves the same way. They need a user service manager and fail without one; they must not be skipped. Each limit test must show that the -limit ends the whole run as `LimitExceeded`. Windows scenes grant the workspace and revoke every grant when -dropped. The `toolchain_acceptance` tests run real toolchains. They are +limit ends the whole run as `LimitExceeded`. Since 0.19.0 the disk test writes +past a 16 MiB limit and expects the `disk` result; the platform tests also +exercise the sampler directly, including, on Unix, a link that must not be +followed and a ceiling reached during a measured scan. Windows scenes grant +the workspace and revoke every grant when dropped. The `toolchain_acceptance` tests run real toolchains. They are `#[ignore]` because they need host toolchains named by `OMGCODE_ACCEPT_*` variables. Run them explicitly with `--ignored` on both platforms and report each language that did not run. A missing variable fails the case rather than @@ -138,6 +141,7 @@ As the relevant components are implemented, include: | Workspace identity | Native paths, stable directory IDs after child writes, ancestor/sibling checks, missing creation-time metadata failure | | Files | Bounded read/list/create/mkdir, policy scope, traversal, native paths, symlinks/junctions, hard links, special files, collisions, uncertain creation, audit privacy, path-swap races, and read-only edit-preview bounds/no-mutation | | Processes | Descendant escape attempts, limits, cleanup, startup failure | +| Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | From 16d89452ef24e4675bfa97d5b9be02accd09bfbf Mon Sep 17 00:00:00 2001 From: James Chapman Date: Fri, 13 Nov 2026 23:37:09 +0000 Subject: [PATCH 02/17] docs: gate package networking behind enforceable destination control Record the package-network profile contract and the primitive review in ADR-0034. No run accepts a profile; --network stays all-or-nothing, and an advisory proxy is rejected because a confined tree can bypass it. Update the execution, development-tool, security, testing, platform, and repository guides. Documentation only; no version bump. Co-Authored-By: Claude Code --- CHANGELOG.md | 5 + IMPLEMENTATION_PLAN.md | 31 +++-- README.md | 7 +- docs/README.md | 2 + ...-behind-enforceable-destination-control.md | 110 ++++++++++++++++++ docs/adr/index.md | 1 + docs/development-tools.md | 21 ++-- docs/execution.md | 52 ++++++++- docs/platform-support.md | 1 + docs/security-coding-rules.md | 5 + docs/testing-standards.md | 1 + 11 files changed, 215 insertions(+), 21 deletions(-) create mode 100644 docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f86eae0..5976a64 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -205,6 +205,11 @@ Changes are recorded here before a release version is assigned. ### Changed +- Package-network destination enforcement is defined as a contract only in + ADR-0034. No run accepts a package-network profile, and `--network` remains + all-or-nothing. An advisory proxy or proxy environment variables are + explicitly rejected because a confined tree can bypass them. This is a + documentation change; no application version is bumped. - The SonarQube Cloud project key is now `OMG-Software_OMGCode`, matching the key a Sonar administrator set on the server. `sonar-project.properties` and the repository-checks guide use the new key. diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index bd571fa..9521ad9 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -56,9 +56,12 @@ This is a resume guide, not a replacement for the owning contracts in tree-wide memory, process, and CPU-time limits. - **PR #29** merged at `4c2a561`: **Phase C6**, version **0.18.0**, with outbound network access behind `task_network` and `--network`. -- This branch, `codex/disk-limit`: **Phase C7**, version **0.19.0**, with a - sampled net disk-growth limit for every trusted run. It started from `main` - at `4c2a561`. +- `codex/disk-limit` (local commit `0426e42`): **Phase C7**, version + **0.19.0**, with a sampled net disk-growth limit for every trusted run. +- This branch, `codex/package-network-profile`: **Phase C8**, a contract-only + package-network profile and implementation gate (ADR-0034). It adds no + runtime flag, no destination enforcement, and no version bump. It is stacked + on C7 at `0426e42`. Implemented today: @@ -126,6 +129,10 @@ Implemented today: [ADR-0031](docs/adr/0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md), [ADR-0032](docs/adr/0032-allow-outbound-network-for-trusted-runs-through-task-network.md), and [ADR-0033](docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). +- A [package-network profile](docs/execution.md#package-network-profile-contract-only) + contract and implementation gate (ADR-0034). No run accepts a profile, no + destination filter exists, and `--network` remains all-or-nothing. This is + configuration/contract work, not an implemented network control. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -470,16 +477,22 @@ on Windows, and trusted CLI commands as the first caller. See - **C6 (merged as PR #29):** outbound network access behind `task_network` and `--network`, with resolver and public certificate paths on Linux. See [ADR-0032](docs/adr/0032-allow-outbound-network-for-trusted-runs-through-task-network.md). -- **C7 (this branch, `codex/disk-limit`):** a sampled net disk-growth limit for - every trusted run. The user chose a disk limit as the next increment. The - supervisor measures the writable roots before the run and once a second on a - separate thread, fails closed when it cannot measure, and records the limit - and peak growth. See +- **C7 (local commit `0426e42` on `codex/disk-limit`):** a sampled net + disk-growth limit for every trusted run. The user chose a disk limit as the + next increment. The supervisor measures the writable roots before the run + and once a second on a separate thread, fails closed when it cannot measure, + and records the limit and peak growth. See [ADR-0033](docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). +- **C8 (this branch, `codex/package-network-profile`):** the package-network + profile contract and implementation gate. The user chose a package-network + profile, then chose contract-only after the primitive review. No run accepts + a profile; an advisory proxy is rejected because the tree can bypass it. + See [ADR-0034](docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md). Next decisions, not yet scheduled: -- a network destination allowlist or package-network profile; +- an enforceable package-network mechanism, registry credentials, and + development-server networking (see ADR-0034); - a model-callable command tool with per-call approval. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index 84597f2..de29398 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,10 @@ directory grants. > Linux run can then reach any address, including loopback and the local > network. On Linux, a run that both the `host_services` preference and its > `--host-services` flag allow can reach the host's Unix-domain sockets, such -> as service and credential-agent sockets. Runs have memory, process-count, -> CPU-time, and sampled disk-growth limits; the disk limit is not a filesystem -> quota. See [command execution](docs/execution.md#tree-limits). +> as service and credential-agent sockets. A package-network profile is +> contract only (ADR-0034) and does not narrow this. Runs have memory, +> process-count, CPU-time, and sampled disk-growth limits; the disk limit is +> not a filesystem quota. See [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/docs/README.md b/docs/README.md index 90128b4..41fda87 100644 --- a/docs/README.md +++ b/docs/README.md @@ -86,6 +86,8 @@ the current commands and limits. There is no frontend yet. The trusted `run` command uses native confinement that was tested on one Windows build and one Linux kernel only. Every trusted run has memory, process-count, CPU-time, and sampled net disk-growth limits; the disk limit is not a filesystem quota. The +package-network profile is contract only (ADR-0034); no run uses it, and +network access remains all-or-nothing. The limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed diff --git a/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md b/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md new file mode 100644 index 0000000..ef434cb --- /dev/null +++ b/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md @@ -0,0 +1,110 @@ +# 0034: Gate package networking behind enforceable destination control + +- Status: Accepted +- Date: 2026-11-13 + +## Context + +The user selected a package-network profile as the next execution increment. +The acceptance case in [development tools](../development-tools.md) requires an +approved profile to reach its declared registry destinations and reject other +destinations. + +Trusted runs have all-or-nothing network access today. `omgcode run --network` +with the `task_network` preference allows every destination on Linux and +internet destinations on Windows; everything else is denied. See +[ADR-0032](0032-allow-outbound-network-for-trusted-runs-through-task-network.md). + +A destination-scoped profile needs a control that a hostile or compromised +package script cannot bypass. The available primitives do not provide one: + +- **Linux Landlock** handles TCP bind and connect by **port**, not by address, + from ABI 4. A rule cannot say "only `registry.example.com`". Seccomp's + classic BPF can inspect syscall numbers and register values, not the + `sockaddr` contents. +- **Windows AppContainer** capabilities are coarse. `internetClient` allows + internet destinations; withholding it allows none, including loopback. There + is no unprivileged destination filter. Windows Filtering Platform, firewall + rules, and loopback exemptions need administrative setup. +- **Proxy environment variables and a loopback proxy** are advisory. A + confined tree can ignore `HTTP_PROXY`, open its own socket, and connect + directly. They cannot enforce a registry list. +- **Filesystem or NTFS quotas are irrelevant to networking.** Host firewall + and nftables rules also need administrative setup. +- A user and network namespace design could isolate egress in principle, but + unprivileged user namespaces are restricted on current Ubuntu, are not + available on Windows, and add a large unsafe surface. A privileged helper is + outside the prototype's unprivileged confinement model. + +## Decision + +Define the package-network profile as a **contract only** and gate any future +implementation: + +1. A package-network profile is an operator-declared, revisioned list of + registry origins: scheme (`https` in normal use; `http` only for a loopback + test fixture), host, optional port, and an optional path prefix. It has no + credentials, wildcards, user information, or redirects to other origins. + It is configuration only and never authorizes execution. +2. No run may use a package-network profile in this phase. `omgcode run` gains + no package-network flag, and `--network` remains all-or-nothing. A profile + is not recorded as a run's authority or network mode. +3. A future implementation must pass all of these gates before it can be + described as implemented: + - the confined tree cannot reach any destination other than the declared + origins or a trusted proxy, including direct IP, IPv6, UDP, DNS, loopback, + alternate socket families, and paths that bypass the proxy; + - the mechanism fails closed when it cannot be applied, and a platform that + cannot enforce it refuses the profile rather than falling back to general + network access; + - the exact limits and bypass analysis are documented, and the mechanism is + qualified on both supported hosts; + - registry credentials remain a separate reviewed design and never enter a + profile, run environment, journal, or model context; + - acceptance tests prove allowed-origin success, undeclared-origin refusal, + redirect refusal, credential refusal, offline fallback, and platform + refusal. +4. Candidate mechanisms for a later decision are a trusted host-side fetch + into a private cache with an offline run, an OS destination filter, or a + Linux-only network-namespace relay. None is selected here. Each needs its + own ADR. + +## Alternatives considered + +- **Advisory proxy plus environment variables.** Rejected: it is not a + boundary; a hostile package script can connect directly. +- **Landlock port allowlist.** Rejected: it cannot name destinations, and any + host on the allowed port remains reachable. +- **`internetClient` plus proxy variables on Windows.** Rejected for the same + reason; the capability cannot be narrowed. +- **Host firewall, nftables, WFP, or loopback exemption.** Rejected for the + prototype: administrative setup, per-host state, and an unqualified + configuration surface. +- **Unprivileged user and network namespaces.** Not selected now: restricted + on current Ubuntu, unavailable on Windows, and a large unsafe addition. +- **Trusted host-side fetch with an offline run.** Deferred to its own + decision. It is enforceable but changes the feature from networked runs to + cache population. + +## Consequences + +- No runtime capability is added, and the product status must not describe + package networking or destination filtering as implemented. +- Package downloads still require the all-or-nothing `task_network` and + `--network` path, or an offline cache the operator prepares. +- The profile contract and the implementation gate are available for a future + increment. Any implementation needs a new ADR, platform qualification, and + acceptance tests. +- The project keeps its rule that a control is not called implemented until + the runtime enforces it. + +## References + +- [Command execution](../execution.md#package-network-profile-contract-only) +- [Development tools](../development-tools.md) +- [Security coding rules](../security-coding-rules.md#provider-traffic-and-tool-calls) +- [Testing standards](../testing-standards.md) +- [ADR-0027](0027-confine-execution-with-native-primitives-starting-with-a-process-tree-core.md) +- [ADR-0028](0028-confine-linux-runs-with-landlock-and-a-socket-filter.md) +- [ADR-0029](0029-confine-windows-runs-in-a-workspace-appcontainer-with-recorded-grants.md) +- [ADR-0032](0032-allow-outbound-network-for-trusted-runs-through-task-network.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 1bd688e..02731c9 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -48,3 +48,4 @@ meaningful alternative does not need an ADR. | [0031: Limit whole run trees with job objects and delegated cgroups](0031-limit-whole-run-trees-with-job-objects-and-delegated-cgroups.md) | Accepted | 2026-11-12 | | [0032: Allow outbound network for trusted runs through task_network](0032-allow-outbound-network-for-trusted-runs-through-task-network.md) | Accepted | 2026-11-13 | | [0033: Bound run disk growth by sampling writable roots](0033-bound-run-disk-growth-by-sampling-writable-roots.md) | Accepted | 2026-11-13 | +| [0034: Gate package networking behind enforceable destination control](0034-gate-package-networking-behind-enforceable-destination-control.md) | Accepted | 2026-11-13 | diff --git a/docs/development-tools.md b/docs/development-tools.md index ff98c26..2b4d4cc 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -125,9 +125,12 @@ Package downloads use task-network permission, never the model connection's permission. Since 0.18.0 a trusted run gets outbound networking only with the workspace `task_network` preference and its `--network` flag; see [network access](execution.md#network-access). There is no destination -allowlist yet. Registry credentials require a narrow reviewed -credential path. Offline tasks must work with available dependencies or explain -which download is needed. +allowlist. The +[package-network profile](execution.md#package-network-profile-contract-only) +is contract only (ADR-0034): no run accepts one, and a proxy or proxy +environment variables are not a boundary. Registry credentials require a +narrow reviewed credential path. Offline tasks must work with available +dependencies or explain which download is needed. Development servers, debuggers, license servers, hardware access, and other services can need extra resources. Treat each as an explicit capability rather @@ -154,9 +157,12 @@ cancellation, denied host-data access, and disabled networking. Include missing dependencies, spaces and native path forms, stale tool profiles, concurrent builds, disk exhaustion, and hostile build/package scripts. -Also prove the allowed case: an approved package-network profile can reach its -declared registry destinations and rejects other destinations. Model-provider -connectivity alone must not enable that package or general task traffic. +The package-network acceptance case cannot run yet. The profile is contract +only (ADR-0034), and no runtime mechanism narrows destinations. A future +implementation must prove that an approved profile reaches its declared +registry destinations and rejects every other destination, including direct +IP, IPv6, UDP, DNS, and proxy-bypass paths. Model-provider connectivity alone +must not enable package or general task traffic. Record the selected profile with task results so failures are reproducible. Do not claim general support from locating an executable or printing its version. @@ -178,7 +184,8 @@ yet: metadata exhaustion; the sampled disk limit is tested with ordinary file growth; - package downloads through `--network`, and rejection of undeclared - destinations, because there is no destination allowlist; + destinations, because there is no destination allowlist and the + package-network profile is contract only (ADR-0034); - hostile package scripts beyond the hostile programs. The Java case has not run on either host. The registry case also remains open. diff --git a/docs/execution.md b/docs/execution.md index a40b909..6a8d6d3 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -46,6 +46,10 @@ run bounds the allocated bytes it may add to its writable roots. No portable per-run disk quota exists, so the supervisor measures growth on a separate thread rather than the kernel enforcing a quota. +The [package-network profile](#package-network-profile-contract-only) is a +contract only (ADR-0034). No run accepts one, and `--network` remains +all-or-nothing. + ## Accepted decisions The user selected these on 2026-11-11; see @@ -203,6 +207,44 @@ as `nscd` or `systemd-resolved` through a Unix socket, need host services too. Windows resolves names and checks certificates through system services, so it adds no paths. +### Package-network profile (contract only) + +The user selected a package-network profile as the next increment. This phase +defines only its contract; see +[ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md). +No run accepts a profile, the runtime has no destination allowlist, and +`--network` remains all-or-nothing. + +A profile, when implemented, is an operator-declared, revisioned list of +registry origins: scheme, host, optional port, and an optional path prefix. +Normal use is `https`; `http` is allowed only for a loopback test fixture. A +profile has no credentials, wildcards, user information, or redirects to +another origin. It is configuration only and never authorizes a run. + +Any implementation must pass these gates before it can be described as +implemented: + +- the confined tree cannot reach any destination other than the declared + origins or a trusted proxy, including direct IP, IPv6, UDP, DNS, loopback, + alternate socket families, and paths that bypass the proxy; +- the mechanism fails closed, and a platform that cannot enforce it refuses + the profile rather than falling back to general network access; +- its exact limits and bypass analysis are documented and qualified on both + supported hosts; +- registry credentials remain a separate reviewed design and never enter a + profile, run environment, journal, or model context; +- acceptance tests prove allowed-origin success, undeclared-origin refusal, + redirect refusal, credential refusal, offline fallback, and platform refusal. + +The current primitives cannot meet that gate. Landlock ABI 4 and later filters +TCP bind and connect by port, not address. Classic seccomp cannot read the +`sockaddr` contents. Windows AppContainer capabilities cannot name +destinations, and granting none blocks loopback too. Proxy environment +variables and an advisory loopback proxy can be bypassed by a hostile tree. +Candidate mechanisms for a later decision are a trusted host-side fetch into a +private cache with an offline run, an OS destination filter, or a Linux-only +network-namespace relay. + ## Container grants A grant gives one workspace's container access to one directory and everything @@ -817,6 +859,11 @@ These remain true after C6: `listen` on an unbound socket, which takes a port the kernel chooses. UDP bind is never limited. See [network access](#network-access). +- **No package-network enforcement.** A package-network profile is contract + only (ADR-0034). No run accepts one, and it does not narrow `--network`. + A proxy or proxy environment variables are not a boundary: a hostile tree + can connect directly. See + [package-network profile](#package-network-profile-contract-only). - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -867,11 +914,12 @@ These remain true after C6: | C5 (0.17.0) | Tree-wide memory, process, and CPU-time limits | Done: see [tree limits](#tree-limits) and ADR-0031 | | C6 (0.18.0) | Outbound network access behind `task_network` and `--network` | Done: see [network access](#network-access) and ADR-0032 | | C7 (0.19.0) | Sampled disk-growth limit for every trusted run | Done: see [disk growth](#disk-growth) and ADR-0033 | +| C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No runtime flag and no destination enforcement. | Later work needs its own decisions: -- a network destination allowlist, registry credentials, and - development-server networking; +- an enforceable package-network destination mechanism, registry credentials, + and development-server networking; - a model-callable command tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/platform-support.md b/docs/platform-support.md index 9b9f610..1bfaf97 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -22,6 +22,7 @@ containment. | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | +| Package networking | Contract only (ADR-0034). No run accepts a package-network profile; `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform ([contract](execution.md#package-network-profile-contract-only)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index a36b3f0..ee7a1c1 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -225,6 +225,11 @@ crate. when a destination or redirect changes. Enabling a destination also permits some data to reach it; do not describe a destination allowlist as content confidentiality. +- Do not enforce a package or task destination list with proxy environment + variables or an advisory loopback proxy: a confined tree can ignore them and + connect directly. A package-network profile is configuration only until a + mechanism constrains every egress path, including direct IP, IPv6, UDP, DNS, + loopback, and alternate socket families. See ADR-0034. - Assemble and validate a complete structured tool call before dispatch. Validate names, arguments, limits, session scope, and provider call identity. A provider adapter must parse provider JSON strictly; the core runtime then diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 7088d4d..005a0f1 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -143,6 +143,7 @@ As the relevant components are implemented, include: | Processes | Descendant escape attempts, limits, cleanup, startup failure | | Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | +| Package network | Contract only, not implemented: no run accepts a profile. A future mechanism must cover allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | From ae2653200be17cea6c2614580e7ca5977966aec1 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Fri, 13 Nov 2026 23:46:32 +0000 Subject: [PATCH 03/17] feat: record package-network profiles as configuration Add operator-declared package-network profiles to the control journal, with package-profile-add/show/remove, strict origin validation, revisioned updates, and bounded storage. Origins require https except for a loopback http test fixture and refuse credentials, queries, fragments, and traversal. No run accepts a profile. --network remains all-or-nothing, no destination filter exists, and a profile never authorizes network access. Version 0.20.0. See ADR-0034. Co-Authored-By: Claude Code --- AGENTS.md | 3 +- CHANGELOG.md | 15 + Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 19 +- README.md | 9 +- crates/omgcode-cli/src/control_cli.rs | 67 ++- crates/omgcode-cli/src/main.rs | 2 + crates/omgcode-cli/tests/control_workflow.rs | 122 ++++++ crates/omgcode-core/src/control.rs | 23 + crates/omgcode-core/src/control/package.rs | 402 ++++++++++++++++++ .../omgcode-core/src/control/package/tests.rs | 240 +++++++++++ docs/README.md | 6 +- ...-behind-enforceable-destination-control.md | 2 + docs/development-tools.md | 21 +- docs/execution.md | 43 +- docs/platform-support.md | 2 +- docs/testing-standards.md | 2 +- docs/workspace-permissions.md | 19 + 19 files changed, 955 insertions(+), 50 deletions(-) create mode 100644 crates/omgcode-core/src/control/package.rs create mode 100644 crates/omgcode-core/src/control/package/tests.rs diff --git a/AGENTS.md b/AGENTS.md index 5c42b83..06443a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,8 @@ filter on Linux or a per-workspace AppContainer on Windows. It never falls back to the unconfined runner. Every run has tree-wide memory, process-count, CPU-time, and sampled net disk-growth limits; on Linux the CLI must run in a delegated cgroup v2. The disk limit measures writable roots and is not a -filesystem quota. Trusted CLI commands record, apply, and revoke +filesystem quota. Package-network profiles are recorded as configuration only; +no run uses them. Trusted CLI commands record, apply, and revoke Windows container ACL grants. Follow the [execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. The core validates replacement records and can prepare protected checkpoints on diff --git a/CHANGELOG.md b/CHANGELOG.md index 5976a64..85731a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,21 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.20.0 records operator-declared package-network profiles as + configuration only. See ADR-0034. + - **Commands:** `workspace package-profile-add`, `package-profile-show`, and + `package-profile-remove` use the expected settings revision. `status` + lists recorded profiles. + - **Contents:** a name and 1 to 8 registry origins. An origin is `https` + with a host, optional port, and optional path prefix; `http` is accepted + only for `localhost`, `127.0.0.1`, or `::1`. Credentials, queries, + fragments, wildcards, and path traversal are refused. + - **Not enforcement:** no run accepts a profile, `--network` remains + all-or-nothing, and no destination filter exists. A profile never + authorizes network access or a run. + - **Records:** `package_profile_added` and `package_profile_removed` events + in the control journal. A control journal written by 0.20.0 cannot be read + by 0.19.0; 0.20.0 reads earlier journals. - Version 0.19.0 bounds each trusted run's net disk growth. See ADR-0033. - **Flag:** `--max-disk-mib` (16 to 1048576, default 8192) is required for every trusted run. A run without a disk limit is refused before anything diff --git a/Cargo.lock b/Cargo.lock index 0b7f678..d1116e7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -592,7 +592,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.19.0" +version = "0.20.0" dependencies = [ "clap", "directories", @@ -605,7 +605,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.19.0" +version = "0.20.0" dependencies = [ "libc", "omgcode-platform", @@ -621,7 +621,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.19.0" +version = "0.20.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 83facfe..08b13c2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.19.0" +version = "0.20.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 9521ad9..ddf0edf 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -58,10 +58,11 @@ This is a resume guide, not a replacement for the owning contracts in outbound network access behind `task_network` and `--network`. - `codex/disk-limit` (local commit `0426e42`): **Phase C7**, version **0.19.0**, with a sampled net disk-growth limit for every trusted run. -- This branch, `codex/package-network-profile`: **Phase C8**, a contract-only - package-network profile and implementation gate (ADR-0034). It adds no - runtime flag, no destination enforcement, and no version bump. It is stacked - on C7 at `0426e42`. +- This branch, `codex/package-network-profile`: **Phase C8** at `16d8945`, + the contract-only package-network profile and implementation gate + (ADR-0034), plus **Phase C9**, version **0.20.0**, with operator-declared + package-network profile records. It is stacked on C7 at `0426e42`. No run + accepts a profile and no destination filter exists. Implemented today: @@ -130,9 +131,9 @@ Implemented today: [ADR-0032](docs/adr/0032-allow-outbound-network-for-trusted-runs-through-task-network.md), and [ADR-0033](docs/adr/0033-bound-run-disk-growth-by-sampling-writable-roots.md). - A [package-network profile](docs/execution.md#package-network-profile-contract-only) - contract and implementation gate (ADR-0034). No run accepts a profile, no - destination filter exists, and `--network` remains all-or-nothing. This is - configuration/contract work, not an implemented network control. + contract and implementation gate (ADR-0034). Version 0.20.0 records + operator-declared profiles as configuration only. No run accepts a profile, + no destination filter exists, and `--network` remains all-or-nothing. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -488,6 +489,10 @@ on Windows, and trusted CLI commands as the first caller. See profile, then chose contract-only after the primitive review. No run accepts a profile; an advisory proxy is rejected because the tree can bypass it. See [ADR-0034](docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md). +- **C9 (this branch, version 0.20.0):** operator-declared package-network + profile records. Profiles are stored through the control journal, with + revisions and strict origin validation. They are configuration only; no run + accepts one and no destination filter exists. Next decisions, not yet scheduled: diff --git a/README.md b/README.md index de29398..a731dff 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,11 @@ directory grants. > Linux run can then reach any address, including loopback and the local > network. On Linux, a run that both the `host_services` preference and its > `--host-services` flag allow can reach the host's Unix-domain sockets, such -> as service and credential-agent sockets. A package-network profile is -> contract only (ADR-0034) and does not narrow this. Runs have memory, -> process-count, CPU-time, and sampled disk-growth limits; the disk limit is -> not a filesystem quota. See [command execution](docs/execution.md#tree-limits). +> as service and credential-agent sockets. Package-network profiles can be +> recorded as configuration only (ADR-0034); no run uses them and they do not +> narrow network access. Runs have memory, process-count, CPU-time, and sampled +> disk-growth limits; the disk limit is not a filesystem quota. See +> [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/crates/omgcode-cli/src/control_cli.rs b/crates/omgcode-cli/src/control_cli.rs index 41c1839..d882eff 100644 --- a/crates/omgcode-cli/src/control_cli.rs +++ b/crates/omgcode-cli/src/control_cli.rs @@ -3,7 +3,9 @@ #![forbid(unsafe_code)] use clap::{Args, Subcommand, ValueEnum}; -use omgcode_core::control::{ContainerGrantAccess, ControlError, ControlStore, ProfileDeclaration}; +use omgcode_core::control::{ + ContainerGrantAccess, ControlError, ControlStore, PackageProfileDeclaration, ProfileDeclaration, +}; use omgcode_core::policy::{Operation, PermissionSet, PolicyRequest, WorkspaceId}; use omgcode_core::run; use serde_json::json; @@ -61,6 +63,28 @@ pub(crate) enum WorkspaceCommand { #[arg(long)] revision: u64, }, + /// Record a package-network profile. Configuration only: no run accepts it. + PackageProfileAdd(PackageProfileAddArgs), + /// Show one recorded package-network profile. + PackageProfileShow { name: String }, + /// Remove a package-network profile. + PackageProfileRemove { + name: String, + #[arg(long)] + revision: u64, + }, +} + +#[derive(Args)] +pub(crate) struct PackageProfileAddArgs { + /// The profile name: ASCII letters, digits, '.', '-', or '_'. + name: String, + /// A registry origin, such as https://registry.example.com/api/. + /// Repeat for each origin. http is accepted only for a loopback fixture. + #[arg(long = "registry", required = true)] + registries: Vec, + #[arg(long)] + revision: u64, } #[derive(Args)] @@ -217,6 +241,29 @@ pub(crate) fn run(action: WorkspaceCommand, data_root: &Path) -> Result<(), CliE stop_withdrawn_runs(data_root, &[])?; print_json(&output) } + WorkspaceCommand::PackageProfileAdd(args) => package_profile_add(args, data_root), + WorkspaceCommand::PackageProfileShow { name } => { + let store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile = store + .package_profile(&name) + .ok_or_else(|| control_error(ControlError::UnknownPackageProfile))?; + print_json(&json!({ "package_profile": profile })) + } + WorkspaceCommand::PackageProfileRemove { name, revision } => { + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile_id = store + .remove_package_profile(&name, revision) + .map_err(control_error)?; + let output = json!({ + "removed_package_profile_id": profile_id, + "snapshot": store.snapshot(), + }); + drop(store); + stop_withdrawn_runs(data_root, &[])?; + print_json(&output) + } WorkspaceCommand::ContainerRevoke { grant } => { let mut store = open_existing(data_root)? .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; @@ -298,6 +345,24 @@ fn profile_add(args: ProfileAddArgs, data_root: &Path) -> Result<(), CliError> { })) } +fn package_profile_add(args: PackageProfileAddArgs, data_root: &Path) -> Result<(), CliError> { + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile = store + .add_package_profile( + &PackageProfileDeclaration { + name: args.name, + origins: args.registries, + }, + args.revision, + ) + .map_err(control_error)?; + print_json(&json!({ + "package_profile_id": profile.id(), + "snapshot": store.snapshot(), + })) +} + fn set_permissions(args: PermissionsArgs, data_root: &Path) -> Result<(), CliError> { if args.read.is_none() && args.write.is_none() diff --git a/crates/omgcode-cli/src/main.rs b/crates/omgcode-cli/src/main.rs index 20232df..3d9611e 100644 --- a/crates/omgcode-cli/src/main.rs +++ b/crates/omgcode-cli/src/main.rs @@ -228,6 +228,8 @@ fn run(cli: Cli) -> Result<(), CliError> { "workspace_container_grants": omgcode_core::control::CONTAINER_GRANTS_SUPPORTED, "workspace_file_tools": false, "toolchain_profiles": RUN_SUPPORTED, + "package_network_profiles": true, + "package_network_enforcement": false, "process_execution": if RUN_SUPPORTED { serde_json::Value::from("trusted_cli_only") } else { diff --git a/crates/omgcode-cli/tests/control_workflow.rs b/crates/omgcode-cli/tests/control_workflow.rs index 85ee09c..6282888 100644 --- a/crates/omgcode-cli/tests/control_workflow.rs +++ b/crates/omgcode-cli/tests/control_workflow.rs @@ -448,6 +448,8 @@ fn capabilities_report_configuration_only_policy_and_trusted_runs_only() { assert_eq!(capabilities["workspace_container_grants"], cfg!(windows)); let runs = cfg!(any(target_os = "linux", windows)); assert_eq!(capabilities["toolchain_profiles"], runs); + assert_eq!(capabilities["package_network_profiles"], true); + assert_eq!(capabilities["package_network_enforcement"], false); if runs { assert_eq!(capabilities["process_execution"], "trusted_cli_only"); } else { @@ -464,6 +466,126 @@ fn capabilities_report_configuration_only_policy_and_trusted_runs_only() { assert!(!data_root.exists()); } +/// Package-network profiles are recorded with revisions but never authorize a +/// run. Invalid origins and duplicates are refused without a revision change. +#[test] +fn package_profiles_are_configuration_only_and_revisioned() { + let temporary = TempDir::new().expect("temporary directory"); + let data_root = temporary.path().join("application-data"); + let development_root = temporary.path().join("development"); + fs::create_dir_all(&development_root).expect("development root"); + let snapshot = set_root(&data_root, &development_root); + let revision = snapshot["revision"].as_u64().expect("revision"); + + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-add", + "crates", + "--registry", + "https://registry.example.com/api/v4", + "--revision", + &revision.to_string(), + ], + ); + assert_success(&output); + let added = json_output(&output); + assert!(added["package_profile_id"].as_str().is_some()); + assert_eq!(added["snapshot"]["package_profiles"][0]["name"], "crates"); + let revision = added["snapshot"]["revision"] + .as_u64() + .expect("revision after add"); + + let output = run_cli(&data_root, &["workspace", "package-profile-show", "CRATES"]); + assert_success(&output); + let shown = json_output(&output); + assert_eq!(shown["package_profile"]["name"], "crates"); + assert_eq!(shown["package_profile"]["origins"][0]["scheme"], "https"); + assert_eq!( + shown["package_profile"]["origins"][0]["host"], + "registry.example.com" + ); + assert_eq!(shown["package_profile"]["origins"][0]["port"], 443); + assert_eq!( + shown["package_profile"]["origins"][0]["path_prefix"], + "/api/v4/" + ); + + let output = run_cli(&data_root, &["workspace", "status"]); + assert_success(&output); + assert_eq!( + json_output(&output)["package_profiles"][0]["name"], + "crates" + ); + + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-add", + "plain", + "--registry", + "http://registry.example.com/", + "--revision", + &revision.to_string(), + ], + ); + assert_control_error(&output); + let output = run_cli(&data_root, &["workspace", "status"]); + assert_eq!( + json_output(&output)["revision"], + Value::from(revision), + "a refused profile changed the revision" + ); + + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-add", + "CRATES", + "--registry", + "https://other.example.com/", + "--revision", + &revision.to_string(), + ], + ); + assert_control_error(&output); + + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-remove", + "crates", + "--revision", + "0", + ], + ); + assert_control_error(&output); + + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-remove", + "crates", + "--revision", + &revision.to_string(), + ], + ); + assert_success(&output); + assert!( + json_output(&output)["snapshot"] + .get("package_profiles") + .is_none() + ); + + let output = run_cli(&data_root, &["workspace", "package-profile-show", "crates"]); + assert_control_error(&output); +} + fn register(data_root: &Path, workspace: &Path, revision: u64) -> String { let output = run_cli( data_root, diff --git a/crates/omgcode-core/src/control.rs b/crates/omgcode-core/src/control.rs index 2362cc4..c917794 100644 --- a/crates/omgcode-core/src/control.rs +++ b/crates/omgcode-core/src/control.rs @@ -23,6 +23,7 @@ use crate::storage::{self, StorageError}; use crate::workspace::DirectoryRecord; mod container; +mod package; mod profile; pub use container::{ @@ -31,6 +32,10 @@ pub use container::{ }; /// Whether this platform can record and apply container grants. pub use omgcode_platform::container::CONTAINER_GRANTS_SUPPORTED; +pub use package::{ + MAX_PACKAGE_ORIGIN_BYTES, MAX_PACKAGE_ORIGINS, MAX_PACKAGE_PROFILES, PackageOrigin, + PackageProfile, PackageProfileDeclaration, PackageProfileStatus, PackageScheme, parse_origin, +}; pub use profile::{ MAX_PROFILE_NAME_CHARS, MAX_PROFILE_PATH_ENTRIES, MAX_PROFILE_ROOTS, MAX_PROFILE_VARIABLES, MAX_PROFILES, MAX_VARIABLE_NAME_BYTES, MAX_VARIABLE_VALUE_BYTES, ProfileDeclaration, @@ -103,6 +108,12 @@ pub enum ControlError { /// The requested toolchain profile is invalid or outside the allowed scope. #[error("toolchain profile refused: {0}")] ProfileRefused(&'static str), + /// No recorded package-network profile has this name. + #[error("package-network profile is not recorded")] + UnknownPackageProfile, + /// The requested package-network profile is invalid. + #[error("package-network profile refused: {0}")] + PackageProfileRefused(&'static str), } impl From for ControlError { @@ -158,6 +169,8 @@ pub struct ControlSnapshot { container_grants: Vec, #[serde(skip_serializing_if = "Vec::is_empty")] profiles: Vec, + #[serde(skip_serializing_if = "Vec::is_empty")] + package_profiles: Vec, /// Container revocations requested per workspace since the journal was /// created. Derived on replay and never serialized; run watchers compare /// it with the count when their run started. @@ -258,6 +271,12 @@ enum Action { ProfileRemoved { profile_id: Uuid, }, + PackageProfileAdded { + profile: PackageProfile, + }, + PackageProfileRemoved { + profile_id: Uuid, + }, } /// One persisted settings/audit event, never prompts or dedicated credential fields. @@ -423,6 +442,7 @@ impl ControlStore { configuration_only: true, container_grants: Vec::new(), profiles: Vec::new(), + package_profiles: Vec::new(), grant_revocations: BTreeMap::new(), }, entries: Vec::new(), @@ -913,6 +933,9 @@ impl ControlStore { Action::ProfileAdded { .. } | Action::ProfileRemoved { .. } => { profile::apply(state, &entry.action, revision)?; } + Action::PackageProfileAdded { .. } | Action::PackageProfileRemoved { .. } => { + package::apply(state, &entry.action, revision)?; + } } state.revision = revision; Ok(()) diff --git a/crates/omgcode-core/src/control/package.rs b/crates/omgcode-core/src/control/package.rs new file mode 100644 index 0000000..94165ea --- /dev/null +++ b/crates/omgcode-core/src/control/package.rs @@ -0,0 +1,402 @@ +//! Operator-declared package-network profiles. +//! +//! A package-network profile names registry origins a future package-fetch +//! mechanism may contact. It is configuration only: no run accepts a profile, +//! and recording one never authorizes network access. The runtime has no +//! destination filter. See `docs/execution.md` and ADR-0034. +//! +//! Origins are stored as parsed fields rather than a free-form URL so replay +//! can check every value without network or DNS. `https` is required except +//! for a loopback `http` test fixture. + +use serde::{Deserialize, Serialize}; +use uuid::Uuid; + +use super::{Action, ControlError, ControlSnapshot, ControlStore, valid_profile_name, valid_uuid}; + +/// Most recorded package-network profiles. +pub const MAX_PACKAGE_PROFILES: usize = 32; +/// Most registry origins in one profile. +pub const MAX_PACKAGE_ORIGINS: usize = 8; +/// Longest registry origin text, in bytes. +pub const MAX_PACKAGE_ORIGIN_BYTES: usize = 2048; +/// Longest registry host, in bytes. +pub const MAX_PACKAGE_HOST_BYTES: usize = 253; +/// Longest registry path prefix, in bytes. +pub const MAX_PACKAGE_PATH_BYTES: usize = 1024; + +/// The scheme a registry origin uses. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum PackageScheme { + /// TLS is required. + Https, + /// Plain HTTP, allowed only for a loopback test fixture. + Http, +} + +impl PackageScheme { + /// The scheme as it appears in a URL. + pub const fn as_str(self) -> &'static str { + match self { + Self::Https => "https", + Self::Http => "http", + } + } +} + +/// One registry origin. No credentials, query, fragment, or wildcard is kept. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct PackageOrigin { + scheme: PackageScheme, + host: String, + port: u16, + /// A path prefix that starts and ends with `/`. + path_prefix: String, +} + +impl PackageOrigin { + /// The origin's scheme. + pub const fn scheme(&self) -> PackageScheme { + self.scheme + } + + /// The origin's host, as the URL parser reports it. An IPv6 literal keeps + /// its brackets. + pub fn host(&self) -> &str { + &self.host + } + + /// The origin's explicit port. + pub const fn port(&self) -> u16 { + self.port + } + + /// The origin's normalized path prefix. + pub fn path_prefix(&self) -> &str { + &self.path_prefix + } +} + +/// A recorded package-network profile. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct PackageProfile { + id: Uuid, + name: String, + origins: Vec, +} + +impl PackageProfile { + /// Stable profile identifier. + pub const fn id(&self) -> Uuid { + self.id + } + + /// The operator's name for the profile. + pub fn name(&self) -> &str { + &self.name + } + + /// Registry origins, in declaration order. + pub fn origins(&self) -> &[PackageOrigin] { + &self.origins + } +} + +/// A profile and the settings revision that recorded it. +#[derive(Clone, Debug, Serialize)] +pub struct PackageProfileStatus { + #[serde(flatten)] + profile: PackageProfile, + revision: u64, +} + +impl PackageProfileStatus { + /// The recorded profile. + pub const fn profile(&self) -> &PackageProfile { + &self.profile + } + + /// The settings revision of the event that added it. + pub const fn revision(&self) -> u64 { + self.revision + } +} + +/// An operator's profile declaration, before any origin is parsed. +#[derive(Clone, Debug, Default)] +pub struct PackageProfileDeclaration { + /// The profile name, with the same rules as a toolchain profile name. + pub name: String, + /// Registry origins. At least one. + pub origins: Vec, +} + +/// Parse one registry origin. +/// +/// The origin must be an absolute `https` URL. `http` is accepted only for +/// `localhost`, `127.0.0.1`, or `::1`. User information, a query, and a +/// fragment are refused. The path is normalized to start and end with `/`. +/// +/// # Errors +/// +/// Returns [`ControlError::PackageProfileRefused`] for a rejected origin. +pub fn parse_origin(text: &str) -> Result { + if text.len() > MAX_PACKAGE_ORIGIN_BYTES { + return Err(refused("a registry origin is too long")); + } + let url = reqwest::Url::parse(text) + .map_err(|_| refused("a registry origin must be an absolute URL"))?; + if !url.username().is_empty() || url.password().is_some() { + return Err(refused("a registry origin must not contain credentials")); + } + if url.query().is_some() { + return Err(refused("a registry origin must not contain a query")); + } + if url.fragment().is_some() { + return Err(refused("a registry origin must not contain a fragment")); + } + let scheme = match url.scheme() { + "https" => PackageScheme::Https, + "http" => PackageScheme::Http, + _ => return Err(refused("a registry origin must use https")), + }; + let host = url + .host_str() + .ok_or_else(|| refused("a registry origin needs a host"))?; + if host.is_empty() || host.len() > MAX_PACKAGE_HOST_BYTES || !host.is_ascii() { + return Err(refused("a registry host is invalid or too long")); + } + if host.ends_with('.') { + return Err(refused("a registry host must not end with a dot")); + } + if scheme == PackageScheme::Http && !is_loopback_host(host) { + return Err(refused("http is allowed only for a loopback test fixture")); + } + let port = url + .port_or_known_default() + .ok_or_else(|| refused("a registry origin needs a port"))?; + if port == 0 { + return Err(refused("a registry origin needs a nonzero port")); + } + let mut path_prefix = url.path().to_owned(); + if path_prefix.is_empty() { + path_prefix.push('/'); + } + if !path_prefix.starts_with('/') { + return Err(refused("a registry path must start with '/'")); + } + if !path_prefix.ends_with('/') { + path_prefix.push('/'); + } + if path_prefix.len() > MAX_PACKAGE_PATH_BYTES { + return Err(refused("a registry path is too long")); + } + if path_prefix + .split('/') + .any(|segment| segment == "." || segment == "..") + { + return Err(refused("a registry path must not contain traversal")); + } + Ok(PackageOrigin { + scheme, + host: host.to_owned(), + port, + path_prefix, + }) +} + +impl ControlStore { + /// Every recorded package-network profile, in the order they were added. + pub fn package_profiles(&self) -> &[PackageProfileStatus] { + &self.snapshot.package_profiles + } + + /// The profile with this name, compared case-insensitively. + pub fn package_profile(&self, name: &str) -> Option<&PackageProfileStatus> { + self.snapshot + .package_profiles + .iter() + .find(|status| status.profile.name.eq_ignore_ascii_case(name)) + } + + /// Record a package-network profile. This advances the settings revision + /// and records no runtime authority. + pub fn add_package_profile( + &mut self, + declaration: &PackageProfileDeclaration, + expected_revision: u64, + ) -> Result { + self.check_revision(expected_revision)?; + if self.package_profiles().len() >= MAX_PACKAGE_PROFILES { + return Err(refused( + "at most 32 package-network profiles may be recorded", + )); + } + if self.package_profile(&declaration.name).is_some() { + return Err(refused( + "a package-network profile with this name already exists; remove it first", + )); + } + let origins = declaration + .origins + .iter() + .map(|origin| parse_origin(origin)) + .collect::, _>>()?; + let profile = PackageProfile { + id: Uuid::new_v4(), + name: declaration.name.clone(), + origins, + }; + validate_profile(&profile)?; + self.append( + Action::PackageProfileAdded { + profile: profile.clone(), + }, + self.next_revision()?, + )?; + Ok(profile) + } + + /// Remove a package-network profile by name. This advances the settings + /// revision. + pub fn remove_package_profile( + &mut self, + name: &str, + expected_revision: u64, + ) -> Result { + self.check_revision(expected_revision)?; + let profile_id = self + .package_profile(name) + .ok_or(ControlError::UnknownPackageProfile)? + .profile + .id; + self.append( + Action::PackageProfileRemoved { profile_id }, + self.next_revision()?, + )?; + Ok(profile_id) + } +} + +/// Validate and apply one package-profile action during replay or append +/// preflight. +pub(super) fn apply( + state: &mut ControlSnapshot, + action: &Action, + revision: u64, +) -> Result<(), ControlError> { + match action { + Action::PackageProfileAdded { profile } => { + validate_profile(profile) + .map_err(|_| ControlError::Invalid("invalid package profile"))?; + if state.package_profiles.len() >= MAX_PACKAGE_PROFILES + || state.package_profiles.iter().any(|status| { + status.profile.id == profile.id + || status.profile.name.eq_ignore_ascii_case(&profile.name) + }) + { + return Err(ControlError::Invalid( + "duplicate package profile or too many package profiles", + )); + } + state.package_profiles.push(PackageProfileStatus { + profile: profile.clone(), + revision, + }); + } + Action::PackageProfileRemoved { profile_id } => { + let index = state + .package_profiles + .iter() + .position(|status| status.profile.id == *profile_id) + .ok_or(ControlError::Invalid( + "removal of an unknown package profile", + ))?; + state.package_profiles.remove(index); + } + _ => {} + } + Ok(()) +} + +/// Check everything about a profile that needs no network or filesystem. +fn validate_profile(profile: &PackageProfile) -> Result<(), ControlError> { + if !valid_uuid(profile.id) || !valid_profile_name(&profile.name) { + return Err(refused( + "package-network profile names are 1 to 64 ASCII letters, digits, '.', '-', or '_', starting with a letter or digit", + )); + } + if profile.origins.is_empty() || profile.origins.len() > MAX_PACKAGE_ORIGINS { + return Err(refused( + "a package-network profile needs 1 to 8 registry origins", + )); + } + for (index, origin) in profile.origins.iter().enumerate() { + validate_origin(origin)?; + if profile.origins[..index] + .iter() + .any(|earlier| same_origin(earlier, origin)) + { + return Err(refused("a registry origin is listed twice")); + } + } + Ok(()) +} + +/// Check stored origin fields, including values that replay could otherwise +/// accept without a URL parse. +fn validate_origin(origin: &PackageOrigin) -> Result<(), ControlError> { + if origin.host.is_empty() + || origin.host.len() > MAX_PACKAGE_HOST_BYTES + || !origin.host.is_ascii() + || origin.host.ends_with('.') + || origin + .host + .chars() + .any(|character| character.is_ascii_control() || character.is_whitespace()) + { + return Err(refused("a registry host is invalid")); + } + if origin.scheme == PackageScheme::Http && !is_loopback_host(&origin.host) { + return Err(refused("http is allowed only for a loopback test fixture")); + } + if origin.port == 0 { + return Err(refused("a registry origin needs a nonzero port")); + } + let path = &origin.path_prefix; + if path.len() > MAX_PACKAGE_PATH_BYTES + || !path.starts_with('/') + || !path.ends_with('/') + || path.chars().any(char::is_control) + || path + .split('/') + .any(|segment| segment == "." || segment == "..") + { + return Err(refused("a registry path prefix is invalid")); + } + Ok(()) +} + +fn same_origin(first: &PackageOrigin, second: &PackageOrigin) -> bool { + first.scheme == second.scheme + && first.host.eq_ignore_ascii_case(&second.host) + && first.port == second.port + && first.path_prefix == second.path_prefix +} + +fn is_loopback_host(host: &str) -> bool { + host.eq_ignore_ascii_case("localhost") + || host == "127.0.0.1" + || host.eq_ignore_ascii_case("::1") + || host.eq_ignore_ascii_case("[::1]") +} + +fn refused(reason: &'static str) -> ControlError { + ControlError::PackageProfileRefused(reason) +} + +#[cfg(test)] +mod tests; diff --git a/crates/omgcode-core/src/control/package/tests.rs b/crates/omgcode-core/src/control/package/tests.rs new file mode 100644 index 0000000..6880c61 --- /dev/null +++ b/crates/omgcode-core/src/control/package/tests.rs @@ -0,0 +1,240 @@ +use super::*; +use std::fs; +use std::path::PathBuf; + +use crate::control::{ControlError, ControlStore, FILE_NAME}; + +fn store() -> (tempfile::TempDir, PathBuf, ControlStore) { + let directory = tempfile::tempdir().expect("temporary directory"); + let data = directory.path().join("data"); + let root = directory.path().join("projects"); + fs::create_dir_all(root.join("app")).expect("development root"); + let mut store = ControlStore::open(&data).expect("store"); + store.set_development_root(&root, 0).expect("root"); + (directory, data, store) +} + +fn declaration(name: &str, origins: &[&str]) -> PackageProfileDeclaration { + PackageProfileDeclaration { + name: name.into(), + origins: origins.iter().map(|origin| (*origin).to_owned()).collect(), + } +} + +/// A profile is recorded with its revision, survives replay, and is removed. +#[test] +fn package_profiles_are_recorded_replayed_and_removed() { + let (_directory, data, mut store) = store(); + let profile = store + .add_package_profile( + &declaration( + "crates", + &[ + "https://registry.example.com/api/v4", + "http://127.0.0.1:8080/repository/", + ], + ), + 1, + ) + .expect("profile"); + assert_eq!(store.revision(), 2); + let status = store + .package_profile("CRATES") + .expect("case-insensitive lookup"); + assert_eq!(status.profile().id(), profile.id()); + assert_eq!(status.revision(), 2); + assert_eq!(status.profile().origins()[0].path_prefix(), "/api/v4/"); + assert_eq!(status.profile().origins()[0].port(), 443); + assert_eq!(status.profile().origins()[1].scheme(), PackageScheme::Http); + assert_eq!(status.profile().origins()[1].port(), 8080); + let encoded = serde_json::to_value(store.snapshot()).expect("snapshot JSON"); + assert_eq!(encoded["package_profiles"][0]["name"], "crates"); + assert_eq!(encoded["package_profiles"][0]["revision"], 2); + drop(store); + + let mut store = ControlStore::open(&data).expect("replay"); + assert_eq!(store.package_profiles().len(), 1); + assert!(matches!( + store.add_package_profile(&declaration("Crates", &["https://other.example.com/"]), 2), + Err(ControlError::PackageProfileRefused(_)) + )); + assert_eq!( + store.remove_package_profile("crates", 2).expect("remove"), + profile.id() + ); + assert_eq!(store.revision(), 3); + assert!(store.package_profiles().is_empty()); + assert!(matches!( + store.remove_package_profile("crates", 3), + Err(ControlError::UnknownPackageProfile) + )); + let encoded = serde_json::to_value(store.snapshot()).expect("snapshot JSON"); + assert!(encoded.get("package_profiles").is_none()); + drop(store); + assert!( + ControlStore::open(&data) + .expect("replay") + .package_profiles() + .is_empty() + ); +} + +/// Origins are normalized, and only https (or loopback http) is accepted. +#[test] +fn origins_are_normalized_and_restricted() { + let origin = parse_origin("https://registry.example.com").expect("default path"); + assert_eq!(origin.scheme(), PackageScheme::Https); + assert_eq!(origin.host(), "registry.example.com"); + assert_eq!(origin.port(), 443); + assert_eq!(origin.path_prefix(), "/"); + + let origin = parse_origin("https://registry.example.com/api/v4").expect("path prefix"); + assert_eq!(origin.path_prefix(), "/api/v4/"); + + let origin = parse_origin("http://localhost:8080/fixture/").expect("loopback http"); + assert_eq!(origin.scheme(), PackageScheme::Http); + assert_eq!(origin.host(), "localhost"); + assert_eq!(origin.port(), 8080); + + let origin = parse_origin("http://[::1]:9000/").expect("IPv6 loopback"); + assert_eq!(origin.host(), "[::1]"); +} + +/// Invalid declarations are refused without an event or revision change. +#[test] +fn invalid_package_profiles_are_refused_without_a_record() { + let (_directory, data, mut store) = store(); + let nine: Vec = (0..9) + .map(|index| format!("https://registry{index}.example.com/")) + .collect(); + let cases = [ + ("no origins", declaration("none", &[])), + ( + "nine origins", + PackageProfileDeclaration { + name: "nine".into(), + origins: nine, + }, + ), + ( + "http outside loopback", + declaration("plain", &["http://registry.example.com/"]), + ), + ( + "credentials", + declaration("credentials", &["https://user@registry.example.com/"]), + ), + ( + "query", + declaration("query", &["https://registry.example.com/?q=1"]), + ), + ( + "fragment", + declaration("fragment", &["https://registry.example.com/#x"]), + ), + ( + "unsupported scheme", + declaration("ftp", &["ftp://registry.example.com/"]), + ), + ( + "zero port", + declaration("port", &["https://registry.example.com:0/"]), + ), + ( + "duplicate origin", + declaration( + "duplicate", + &[ + "https://registry.example.com/", + "https://REGISTRY.example.com/", + ], + ), + ), + ( + "bad name", + declaration("bad name", &["https://registry.example.com/"]), + ), + ( + "empty name", + declaration("", &["https://registry.example.com/"]), + ), + ]; + for (name, declaration) in cases { + let result = store.add_package_profile(&declaration, 1); + assert!( + matches!(result, Err(ControlError::PackageProfileRefused(_))), + "{name}: {result:?}" + ); + } + assert_eq!(store.revision(), 1); + assert!(store.package_profiles().is_empty()); + drop(store); + let text = fs::read_to_string(data.join(FILE_NAME)).expect("journal text"); + assert!(!text.contains("package_profile_added"), "{text}"); +} + +/// Global profile and per-profile origin bounds are enforced. +#[test] +fn package_profile_bounds_are_enforced() { + let (_directory, _data, mut store) = store(); + for index in 0..MAX_PACKAGE_PROFILES { + let revision = store.revision(); + store + .add_package_profile( + &declaration(&format!("p{index}"), &["https://registry.example.com/"]), + revision, + ) + .expect("profile within the bound"); + } + let revision = store.revision(); + assert!(matches!( + store.add_package_profile( + &declaration("extra", &["https://registry.example.com/"]), + revision + ), + Err(ControlError::PackageProfileRefused(_)) + )); + + let revision = store.revision(); + store + .remove_package_profile("p0", revision) + .expect("free a profile slot"); + let host = format!("{}{}", "a".repeat(200), "b".repeat(52)); + let path = format!("/{}/", "c".repeat(1000)); + let origins: Vec = (0..MAX_PACKAGE_ORIGINS) + .map(|index| format!("https://{index}{host}{path}")) + .collect(); + let revision = store.revision(); + store + .add_package_profile( + &PackageProfileDeclaration { + name: "largest".into(), + origins, + }, + revision, + ) + .expect("a full profile fits one event"); +} + +/// Replay rejects a profile whose stored origin would fail the declaration +/// rules, even though it was not parsed from a URL this time. +#[test] +fn replay_refuses_a_tampered_package_profile() { + let (_directory, data, mut store) = store(); + store + .add_package_profile( + &declaration("crates", &["https://registry.example.com/"]), + 1, + ) + .expect("profile"); + drop(store); + let journal = data.join(FILE_NAME); + let text = fs::read_to_string(&journal).expect("journal text"); + let tampered = text.replacen("\"scheme\":\"https\"", "\"scheme\":\"http\"", 1); + assert_ne!(text, tampered); + fs::write(&journal, tampered).expect("tamper journal"); + assert!(matches!( + ControlStore::open(&data), + Err(ControlError::Invalid(_)) + )); +} diff --git a/docs/README.md b/docs/README.md index 41fda87..ae352cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -85,9 +85,9 @@ separate documentation tests on Windows and Linux. The development guide owns the current commands and limits. There is no frontend yet. The trusted `run` command uses native confinement that was tested on one Windows build and one Linux kernel only. Every trusted run has memory, process-count, CPU-time, and -sampled net disk-growth limits; the disk limit is not a filesystem quota. The -package-network profile is contract only (ADR-0034); no run uses it, and -network access remains all-or-nothing. The +sampled net disk-growth limits; the disk limit is not a filesystem quota. +Package-network profiles are recorded as configuration only (ADR-0034); no run +uses them, and network access remains all-or-nothing. The limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed diff --git a/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md b/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md index ef434cb..f4e8f2b 100644 --- a/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md +++ b/docs/adr/0034-gate-package-networking-behind-enforceable-destination-control.md @@ -90,6 +90,8 @@ implementation: - No runtime capability is added, and the product status must not describe package networking or destination filtering as implemented. +- Version 0.20.0 records operator-declared profiles as configuration. That does + not change this gate, and no run accepts one. - Package downloads still require the all-or-nothing `task_network` and `--network` path, or an offline cache the operator prepares. - The profile contract and the implementation gate are available for a future diff --git a/docs/development-tools.md b/docs/development-tools.md index 2b4d4cc..f793cf6 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -127,10 +127,11 @@ workspace `task_network` preference and its `--network` flag; see [network access](execution.md#network-access). There is no destination allowlist. The [package-network profile](execution.md#package-network-profile-contract-only) -is contract only (ADR-0034): no run accepts one, and a proxy or proxy -environment variables are not a boundary. Registry credentials require a -narrow reviewed credential path. Offline tasks must work with available -dependencies or explain which download is needed. +is recorded as configuration only (ADR-0034): `workspace +package-profile-add/show/remove` store registry origins, but no run accepts a +profile, and a proxy or proxy environment variables are not a boundary. +Registry credentials require a narrow reviewed credential path. Offline tasks +must work with available dependencies or explain which download is needed. Development servers, debuggers, license servers, hardware access, and other services can need extra resources. Treat each as an explicit capability rather @@ -157,12 +158,12 @@ cancellation, denied host-data access, and disabled networking. Include missing dependencies, spaces and native path forms, stale tool profiles, concurrent builds, disk exhaustion, and hostile build/package scripts. -The package-network acceptance case cannot run yet. The profile is contract -only (ADR-0034), and no runtime mechanism narrows destinations. A future -implementation must prove that an approved profile reaches its declared -registry destinations and rejects every other destination, including direct -IP, IPv6, UDP, DNS, and proxy-bypass paths. Model-provider connectivity alone -must not enable package or general task traffic. +The package-network acceptance case cannot run yet. Profiles are recorded as +configuration only (ADR-0034), and no runtime mechanism narrows destinations. +A future implementation must prove that an approved profile reaches its +declared registry destinations and rejects every other destination, including +direct IP, IPv6, UDP, DNS, and proxy-bypass paths. Model-provider connectivity +alone must not enable package or general task traffic. Record the selected profile with task results so failures are reproducible. Do not claim general support from locating an executable or printing its version. diff --git a/docs/execution.md b/docs/execution.md index 6a8d6d3..e4c9752 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -46,9 +46,9 @@ run bounds the allocated bytes it may add to its writable roots. No portable per-run disk quota exists, so the supervisor measures growth on a separate thread rather than the kernel enforcing a quota. -The [package-network profile](#package-network-profile-contract-only) is a -contract only (ADR-0034). No run accepts one, and `--network` remains -all-or-nothing. +The [package-network profile](#package-network-profile-contract-only) is +recorded as configuration only (ADR-0034) since version 0.20.0. No run accepts +one, and `--network` remains all-or-nothing. ## Accepted decisions @@ -209,17 +209,23 @@ adds no paths. ### Package-network profile (contract only) -The user selected a package-network profile as the next increment. This phase -defines only its contract; see -[ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md). -No run accepts a profile, the runtime has no destination allowlist, and -`--network` remains all-or-nothing. +The user selected a package-network profile as the next increment. +[ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md) +defines its contract, and version 0.20.0 records operator-declared profiles as +configuration. No run accepts a profile, the runtime has no destination +allowlist, and `--network` remains all-or-nothing. -A profile, when implemented, is an operator-declared, revisioned list of -registry origins: scheme, host, optional port, and an optional path prefix. -Normal use is `https`; `http` is allowed only for a loopback test fixture. A -profile has no credentials, wildcards, user information, or redirects to -another origin. It is configuration only and never authorizes a run. +A profile is an operator-declared, revisioned list of registry origins: +scheme, host, optional port, and an optional path prefix. Normal use is +`https`; `http` is allowed only for a loopback test fixture. A profile has no +credentials, wildcards, user information, or redirects to another origin. It +is configuration only and never authorizes a run. At most 32 profiles are +recorded, each with 1 to 8 origins. + +`workspace package-profile-add --registry ... --revision `, +`package-profile-show `, and +`package-profile-remove --revision ` manage the records. Each +mutation needs the expected settings revision and increments it. Any implementation must pass these gates before it can be described as implemented: @@ -859,10 +865,10 @@ These remain true after C6: `listen` on an unbound socket, which takes a port the kernel chooses. UDP bind is never limited. See [network access](#network-access). -- **No package-network enforcement.** A package-network profile is contract - only (ADR-0034). No run accepts one, and it does not narrow `--network`. - A proxy or proxy environment variables are not a boundary: a hostile tree - can connect directly. See +- **No package-network enforcement.** Package-network profiles are recorded as + configuration only (ADR-0034). No run accepts one, and it does not narrow + `--network`. A proxy or proxy environment variables are not a boundary: a + hostile tree can connect directly. See [package-network profile](#package-network-profile-contract-only). - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system @@ -914,7 +920,8 @@ These remain true after C6: | C5 (0.17.0) | Tree-wide memory, process, and CPU-time limits | Done: see [tree limits](#tree-limits) and ADR-0031 | | C6 (0.18.0) | Outbound network access behind `task_network` and `--network` | Done: see [network access](#network-access) and ADR-0032 | | C7 (0.19.0) | Sampled disk-growth limit for every trusted run | Done: see [disk growth](#disk-growth) and ADR-0033 | -| C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No runtime flag and no destination enforcement. | +| C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No destination enforcement. | +| C9 (0.20.0) | Package-network profile records | Done as configuration: `workspace package-profile-add/show/remove` and the control journal events. No run accepts a profile. | Later work needs its own decisions: diff --git a/docs/platform-support.md b/docs/platform-support.md index 1bfaf97..88c9a7e 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -22,7 +22,7 @@ containment. | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | -| Package networking | Contract only (ADR-0034). No run accepts a package-network profile; `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform ([contract](execution.md#package-network-profile-contract-only)) | +| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform (ADR-0034) ([contract](execution.md#package-network-profile-contract-only)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 005a0f1..23657ca 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -143,7 +143,7 @@ As the relevant components are implemented, include: | Processes | Descendant escape attempts, limits, cleanup, startup failure | | Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | -| Package network | Contract only, not implemented: no run accepts a profile. A future mechanism must cover allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md)) | +| Package network | Profile storage is implemented: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, and removal. No run accepts a profile and no destination filter exists. A future mechanism must cover allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | diff --git a/docs/workspace-permissions.md b/docs/workspace-permissions.md index 2834ecc..1e343f0 100644 --- a/docs/workspace-permissions.md +++ b/docs/workspace-permissions.md @@ -114,6 +114,10 @@ zero-based sequence, UTC timestamp, global revision, and tagged `action`: | `workspace_registered` | New ID, directory identity, default preferences; increment revision | | `permissions_changed` | Existing ID and complete preference set; increment revision | | `policy_checked` | Explicit diagnostic binding/request check and decision; preserve revision | +| `profile_added` | New toolchain profile; increment revision | +| `profile_removed` | Remove a toolchain profile; increment revision | +| `package_profile_added` | New package-network profile; increment revision | +| `package_profile_removed` | Remove a package-network profile; increment revision | Operational file checks do not append `policy_checked`. They use current settings and their separate [operation journal](file-access.md). This prevents @@ -167,6 +171,21 @@ that records a profile. The [execution guide](execution.md#toolchain-profiles) owns the rules. Profile variables are stored here in plain text; never put secrets in them. +## Package-network profiles + +`workspace package-profile-add`, `package-profile-show`, and +`package-profile-remove` record operator-declared registry origins as +configuration only. Adding and removing need the expected revision and +increment it, through the `package_profile_added` and +`package_profile_removed` events. `workspace status` lists profiles under +`package_profiles` and omits the field until a profile exists. Each profile +has a name and 1 to 8 origins; there are at most 32 profiles, and one origin +text is at most 2,048 bytes. No run accepts a profile, and a profile never +authorizes network access. Version 0.19.0 refuses a settings log that records +one; a 0.20.0 control journal cannot be read by 0.19.0. The +[execution guide](execution.md#package-network-profile-contract-only) owns the +contract and the remaining enforcement gate. + ## Task network `workspace permissions --revision --task-network true` lets a From 16e2c4e70cc84e611ce7e370620292ed9559e99a Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 00:00:29 +0000 Subject: [PATCH 04/17] feat: fetch packages through a trusted allowlisted cache Add `omgcode packages fetch`, a trusted operator command that contacts only origins declared in a recorded package-network profile and writes one bounded response into a private per-workspace cache. It requires task_network, refuses redirects, credentials, queries, and fragments, uses system TLS trust, caps and hashes the body, and never overwrites an existing cache name. The control journal records start and finish events with the URL digest, not its text. The confined run remains offline and does not yet read the cache. Version 0.21.0. See ADR-0035. Co-Authored-By: Claude Code --- AGENTS.md | 6 +- CHANGELOG.md | 20 + Cargo.lock | 238 ++++++++- Cargo.toml | 4 +- IMPLEMENTATION_PLAN.md | 23 +- README.md | 8 +- crates/omgcode-cli/src/main.rs | 8 + crates/omgcode-cli/src/packages_cli.rs | 86 +++ crates/omgcode-cli/tests/control_workflow.rs | 1 + crates/omgcode-cli/tests/packages_workflow.rs | 245 +++++++++ crates/omgcode-core/src/control.rs | 17 +- crates/omgcode-core/src/control/package.rs | 189 +++++++ crates/omgcode-core/src/lib.rs | 1 + crates/omgcode-core/src/packages.rs | 490 ++++++++++++++++++ crates/omgcode-core/src/packages/tests.rs | 321 ++++++++++++ docs/README.md | 4 +- ...ges-through-a-trusted-allowlisted-cache.md | 102 ++++ docs/adr/index.md | 1 + docs/development-tools.md | 23 +- docs/execution.md | 69 ++- docs/platform-support.md | 2 +- docs/security-coding-rules.md | 6 + docs/testing-standards.md | 2 +- docs/workspace-permissions.md | 9 + 24 files changed, 1829 insertions(+), 46 deletions(-) create mode 100644 crates/omgcode-cli/src/packages_cli.rs create mode 100644 crates/omgcode-cli/tests/packages_workflow.rs create mode 100644 crates/omgcode-core/src/packages.rs create mode 100644 crates/omgcode-core/src/packages/tests.rs create mode 100644 docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md diff --git a/AGENTS.md b/AGENTS.md index 06443a5..de91520 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,8 +19,10 @@ to the unconfined runner. Every run has tree-wide memory, process-count, CPU-time, and sampled net disk-growth limits; on Linux the CLI must run in a delegated cgroup v2. The disk limit measures writable roots and is not a filesystem quota. Package-network profiles are recorded as configuration only; -no run uses them. Trusted CLI commands record, apply, and revoke -Windows container ACL grants. Follow the [execution contract](docs/execution.md). +no run uses them. The trusted `packages fetch` command downloads from declared +origins into a private cache, and the run does not yet read it. Trusted CLI +commands record, apply, and revoke Windows container ACL grants. Follow the +[execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. The core validates replacement records and can prepare protected checkpoints on Linux and Windows through a live authorized binding. The CLI provides diff --git a/CHANGELOG.md b/CHANGELOG.md index 85731a3..836226f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,26 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.21.0 adds the trusted operator command `omgcode packages fetch` + and a private allowlisted package cache. See ADR-0035. + - **Command:** `packages fetch --profile --url + --name [--max-bytes ] [--timeout-secs ]`. + - **Gating:** trusted CLI only; never a model tool. The workspace must be + registered and enable `task_network`. + - **Destination:** the URL must match a recorded origin's scheme, host, + port, and path prefix. Normal use is `https`; `http` is accepted only for + loopback tests. Credentials, queries, fragments, and redirects are + refused. Proxy environment variables are ignored. + - **Transport:** system TLS trust through `reqwest`'s `native-tls` feature; + certificate validation is never disabled. + - **Bounds:** one GET, 1 byte to 1 GiB, 1 to 600 seconds. The body is + streamed, hashed with SHA-256, and stopped at the limit. + - **Cache:** `/package-cache//`, private + directories and files, exclusive name, temporary file then rename. No + power-loss claim. The run does not yet read the cache. + - **Audit:** `package_fetch_started` and `package_fetch_finished` in the + control journal preserve the settings revision and omit the URL text. A + control journal written by 0.21.0 cannot be read by 0.20.0. - Version 0.20.0 records operator-declared package-network profiles as configuration only. See ADR-0034. - **Commands:** `workspace package-profile-add`, `package-profile-show`, and diff --git a/Cargo.lock b/Cargo.lock index d1116e7..3188511 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -91,6 +91,16 @@ version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" +[[package]] +name = "cc" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ff2a8126fff0f8c839080d619675a585e61720bb12d2baceae45769fd66f155" +dependencies = [ + "find-msvc-tools", + "shlex", +] + [[package]] name = "cfg-if" version = "1.0.5" @@ -128,7 +138,7 @@ dependencies = [ "heck", "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] @@ -149,6 +159,22 @@ version = "0.10.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c" +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + [[package]] name = "cpufeatures" version = "0.3.1" @@ -216,7 +242,7 @@ checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] @@ -235,6 +261,27 @@ version = "2.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "foreign-types" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1" +dependencies = [ + "foreign-types-shared", +] + +[[package]] +name = "foreign-types-shared" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b" + [[package]] name = "form_urlencoded" version = "1.2.2" @@ -377,6 +424,22 @@ dependencies = [ "want", ] +[[package]] +name = "hyper-tls" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0" +dependencies = [ + "bytes", + "http-body-util", + "hyper", + "hyper-util", + "native-tls", + "tokio", + "tokio-native-tls", + "tower-service", +] + [[package]] name = "hyper-util" version = "0.1.21" @@ -584,6 +647,23 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "native-tls" +version = "0.2.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2" +dependencies = [ + "libc", + "log", + "openssl", + "openssl-probe", + "openssl-sys", + "schannel", + "security-framework", + "security-framework-sys", + "tempfile", +] + [[package]] name = "num-conv" version = "0.2.2" @@ -592,7 +672,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.20.0" +version = "0.21.0" dependencies = [ "clap", "directories", @@ -605,7 +685,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.20.0" +version = "0.21.0" dependencies = [ "libc", "omgcode-platform", @@ -621,7 +701,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.20.0" +version = "0.21.0" dependencies = [ "libc", "rustix", @@ -641,6 +721,49 @@ version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "openssl" +version = "0.10.81" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77823a27f0babb03091cb9ed9ef80af3b39dbc82f97e8fa530374b7dafd87a45" +dependencies = [ + "bitflags", + "cfg-if", + "foreign-types", + "libc", + "openssl-macros", + "openssl-sys", +] + +[[package]] +name = "openssl-macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "openssl-probe" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e036b411754132fd6b74e94b74e9a13c5cf606fa93d1885c35860d3060820b1" + +[[package]] +name = "openssl-sys" +version = "0.9.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b47e7e6bb2c38cd930d25a23b40fa52e068c10e85f3e03a7f5ba5aaca5713695" +dependencies = [ + "cc", + "libc", + "pkg-config", + "vcpkg", +] + [[package]] name = "option-ext" version = "0.2.0" @@ -659,6 +782,12 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + [[package]] name = "potential_utf" version = "0.1.6" @@ -723,15 +852,19 @@ dependencies = [ "http-body", "http-body-util", "hyper", + "hyper-tls", "hyper-util", "js-sys", "log", + "native-tls", "percent-encoding", "pin-project-lite", + "rustls-pki-types", "serde", "serde_json", "sync_wrapper", "tokio", + "tokio-native-tls", "tower", "tower-http", "tower-service", @@ -754,12 +887,53 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "rustls-pki-types" +version = "1.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "102f35f7de7b06d8c61f1cff6592f5253e0dea431c74867aad5dfd70f44663fb" +dependencies = [ + "zeroize", +] + [[package]] name = "rustversion" version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" +[[package]] +name = "schannel" +version = "0.1.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9cb23c424d8ee841bb4d813677ca237e2a610067d594fec130f87d6093495ab5" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags", + "core-foundation", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + [[package]] name = "serde" version = "1.0.229" @@ -787,7 +961,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] @@ -814,6 +988,12 @@ dependencies = [ "digest", ] +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + [[package]] name = "slab" version = "0.4.12" @@ -848,6 +1028,17 @@ version = "0.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + [[package]] name = "syn" version = "3.0.9" @@ -876,7 +1067,7 @@ checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] @@ -909,7 +1100,7 @@ checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] @@ -958,6 +1149,7 @@ version = "1.54.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" dependencies = [ + "bytes", "libc", "mio", "pin-project-lite", @@ -965,6 +1157,16 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "tokio-native-tls" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2" +dependencies = [ + "native-tls", + "tokio", +] + [[package]] name = "tower" version = "0.5.3" @@ -1092,6 +1294,12 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + [[package]] name = "want" version = "0.3.2" @@ -1149,7 +1357,7 @@ dependencies = [ "bumpalo", "proc-macro2", "quote", - "syn", + "syn 3.0.9", "wasm-bindgen-shared", ] @@ -1212,7 +1420,7 @@ checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", "synstructure", ] @@ -1233,10 +1441,16 @@ checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", "synstructure", ] +[[package]] +name = "zeroize" +version = "1.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" + [[package]] name = "zerotrie" version = "0.2.5" @@ -1267,7 +1481,7 @@ checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index 08b13c2..485760a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.20.0" +version = "0.21.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" @@ -16,7 +16,7 @@ serde_json = "1" uuid = { version = "1", features = ["v4", "serde"] } time = { version = "0.3", features = ["formatting", "parsing", "serde"] } thiserror = "2" -reqwest = { version = "0.13.5", default-features = false, features = ["blocking", "json"] } +reqwest = { version = "0.13.5", default-features = false, features = ["blocking", "json", "native-tls"] } sha2 = "0.11.1" clap = { version = "4.6.7", features = ["derive"] } directories = "6" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index ddf0edf..f6cd910 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -60,9 +60,11 @@ This is a resume guide, not a replacement for the owning contracts in **0.19.0**, with a sampled net disk-growth limit for every trusted run. - This branch, `codex/package-network-profile`: **Phase C8** at `16d8945`, the contract-only package-network profile and implementation gate - (ADR-0034), plus **Phase C9**, version **0.20.0**, with operator-declared - package-network profile records. It is stacked on C7 at `0426e42`. No run - accepts a profile and no destination filter exists. + (ADR-0034), **Phase C9**, version **0.20.0**, with operator-declared + package-network profile records, and **Phase C10**, version **0.21.0**, with + the trusted allowlisted package fetch and private cache (ADR-0035). It is + stacked on C7 at `0426e42`. No run accepts a profile or reads the cache, and + no run destination filter exists. Implemented today: @@ -134,6 +136,11 @@ Implemented today: contract and implementation gate (ADR-0034). Version 0.20.0 records operator-declared profiles as configuration only. No run accepts a profile, no destination filter exists, and `--network` remains all-or-nothing. +- A trusted [`packages fetch`](docs/execution.md#trusted-package-fetch) + command (ADR-0035). It contacts only declared origins, refuses redirects and + credentials, bounds and hashes the response, writes a private per-workspace + cache, and records the intent and outcome. The run remains offline and does + not yet read the cache. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -493,11 +500,17 @@ on Windows, and trusted CLI commands as the first caller. See profile records. Profiles are stored through the control journal, with revisions and strict origin validation. They are configuration only; no run accepts one and no destination filter exists. +- **C10 (this branch, version 0.21.0):** the trusted allowlisted package + fetch. The user selected a trusted host-side fetch into a private cache. The + command contacts only declared origins, refuses redirects and credentials, + bounds and hashes the body, and audits the intent and outcome. The run + remains offline and does not read the cache. See + [ADR-0035](docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md). Next decisions, not yet scheduled: -- an enforceable package-network mechanism, registry credentials, and - development-server networking (see ADR-0034); +- exposing the package cache to runs read-only, registry credentials, and + development-server networking; - a model-callable command tool with per-call approval. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index a731dff..02f5bc5 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,9 @@ directory grants. > `--host-services` flag allow can reach the host's Unix-domain sockets, such > as service and credential-agent sockets. Package-network profiles can be > recorded as configuration only (ADR-0034); no run uses them and they do not -> narrow network access. Runs have memory, process-count, CPU-time, and sampled +> narrow network access. The trusted `packages fetch` command downloads from +> declared origins into a private cache; the run remains offline and does not +> yet read that cache. Runs have memory, process-count, CPU-time, and sampled > disk-growth limits; the disk limit is not a filesystem quota. See > [command execution](docs/execution.md#tree-limits). @@ -67,6 +69,10 @@ and `omgcode-platform`. The CLI command is `omgcode`. It provides: with a recorded toolchain profile, and inspect, acknowledge, or archive the run journal. Output is printed, never stored. See [command execution](docs/execution.md#trusted-runs). +- `packages fetch`: download one URL from a declared package-network origin + into a private per-workspace cache. It is a trusted operator command, never + a model tool, and the confined run still has no network access. See + [trusted package fetch](docs/execution.md#trusted-package-fetch). - `file`: use bounded native reads, listings, exclusive new-file creation, single-directory creation, and read-only diff previews through explicit workspace/session CLI selections. These trusted operator commands do not diff --git a/crates/omgcode-cli/src/main.rs b/crates/omgcode-cli/src/main.rs index 3d9611e..6ecb5c1 100644 --- a/crates/omgcode-cli/src/main.rs +++ b/crates/omgcode-cli/src/main.rs @@ -4,6 +4,7 @@ mod control_cli; mod file_cli; mod model_tools; +mod packages_cli; mod run_cli; use clap::{Args, Parser, Subcommand}; @@ -68,6 +69,11 @@ enum Command { #[command(subcommand)] action: run_cli::RunsCommand, }, + /// Fetch a package from a declared registry into a private cache. + Packages { + #[command(subcommand)] + action: packages_cli::PackagesCommand, + }, } #[derive(Subcommand)] @@ -230,6 +236,7 @@ fn run(cli: Cli) -> Result<(), CliError> { "toolchain_profiles": RUN_SUPPORTED, "package_network_profiles": true, "package_network_enforcement": false, + "package_fetch": true, "process_execution": if RUN_SUPPORTED { serde_json::Value::from("trusted_cli_only") } else { @@ -293,6 +300,7 @@ fn run(cli: Cli) -> Result<(), CliError> { Command::Chat(args) => chat(cli.data_dir, args), Command::Run(args) => run_cli::run(args, &data_root(cli.data_dir)?), Command::Runs { action } => run_cli::runs(action, &data_root(cli.data_dir)?), + Command::Packages { action } => packages_cli::run(action, &data_root(cli.data_dir)?), } } diff --git a/crates/omgcode-cli/src/packages_cli.rs b/crates/omgcode-cli/src/packages_cli.rs new file mode 100644 index 0000000..69a7103 --- /dev/null +++ b/crates/omgcode-cli/src/packages_cli.rs @@ -0,0 +1,86 @@ +//! Trusted operator package fetches. +#![forbid(unsafe_code)] + +use std::path::Path; +use std::str::FromStr; +use std::time::Duration; + +use clap::{Args, Subcommand}; +use omgcode_core::packages::{ + self, DEFAULT_FETCH_TIMEOUT, DEFAULT_MAX_FETCH_BYTES, FetchError, FetchRequest, + MAX_FETCH_BYTES, MAX_FETCH_TIMEOUT, +}; +use omgcode_core::policy::WorkspaceId; +use serde_json::json; + +use crate::{CliError, print_json}; + +/// Fetch one package from a declared registry into a private cache. +#[derive(Subcommand)] +pub(crate) enum PackagesCommand { + Fetch(FetchArgs), +} + +#[derive(Args)] +pub(crate) struct FetchArgs { + /// The registered workspace whose private cache receives the file. + workspace: String, + /// The recorded package-network profile to use. + #[arg(long)] + profile: String, + /// The absolute registry URL. It must match a declared origin and path. + #[arg(long)] + url: String, + /// The cache file name. It must be a new single file name. + #[arg(long)] + name: String, + /// Greatest response body accepted (1 to 1073741824 bytes). + #[arg(long, default_value_t = DEFAULT_MAX_FETCH_BYTES)] + max_bytes: u64, + /// Request deadline (1 to 600 seconds). + #[arg(long, default_value_t = DEFAULT_FETCH_TIMEOUT.as_secs())] + timeout_secs: u64, +} + +/// Run one trusted package command. +pub(crate) fn run(action: PackagesCommand, data_root: &Path) -> Result<(), CliError> { + match action { + PackagesCommand::Fetch(args) => fetch(args, data_root), + } +} + +fn fetch(args: FetchArgs, data_root: &Path) -> Result<(), CliError> { + let workspace_id = WorkspaceId::from_str(&args.workspace) + .map_err(|_| CliError::new("configuration", "Invalid workspace identifier"))?; + if args.max_bytes == 0 || args.max_bytes > MAX_FETCH_BYTES { + return Err(CliError::new( + "configuration", + "Byte limit must be 1 to 1073741824", + )); + } + if args.timeout_secs == 0 || Duration::from_secs(args.timeout_secs) > MAX_FETCH_TIMEOUT { + return Err(CliError::new( + "configuration", + "Timeout must be 1 to 600 seconds", + )); + } + let request = FetchRequest { + workspace_id, + profile: args.profile, + url: args.url, + name: args.name, + max_bytes: args.max_bytes, + timeout: Duration::from_secs(args.timeout_secs), + }; + match packages::fetch(data_root, &request) { + Ok(report) => print_json(&json!({ "fetch": report })), + Err(FetchError::OutcomeNotRecorded { report, source }) => { + print_json(&json!({ "fetch": report }))?; + Err(CliError::new( + "packages", + format!("The package was fetched, but its outcome could not be recorded: {source}"), + )) + } + Err(error) => Err(CliError::new("packages", error.to_string())), + } +} diff --git a/crates/omgcode-cli/tests/control_workflow.rs b/crates/omgcode-cli/tests/control_workflow.rs index 6282888..c533a7d 100644 --- a/crates/omgcode-cli/tests/control_workflow.rs +++ b/crates/omgcode-cli/tests/control_workflow.rs @@ -450,6 +450,7 @@ fn capabilities_report_configuration_only_policy_and_trusted_runs_only() { assert_eq!(capabilities["toolchain_profiles"], runs); assert_eq!(capabilities["package_network_profiles"], true); assert_eq!(capabilities["package_network_enforcement"], false); + assert_eq!(capabilities["package_fetch"], true); if runs { assert_eq!(capabilities["process_execution"], "trusted_cli_only"); } else { diff --git a/crates/omgcode-cli/tests/packages_workflow.rs b/crates/omgcode-cli/tests/packages_workflow.rs new file mode 100644 index 0000000..03b1c27 --- /dev/null +++ b/crates/omgcode-cli/tests/packages_workflow.rs @@ -0,0 +1,245 @@ +//! Trusted package fetch through the real CLI with a local registry fixture. +#![cfg(any(target_os = "linux", windows))] + +mod support; + +use std::fs; +use std::io::{self, Read, Write}; +use std::net::{SocketAddr, TcpListener, TcpStream}; +use std::path::Path; +use std::thread::{self, JoinHandle}; +use std::time::{Duration, Instant}; + +use support::{assert_error_code, assert_success, json_output, path_arg, run_cli}; +use tempfile::TempDir; + +const PROFILE: &str = "registries"; +const BODY: &[u8] = b"fetched-package-bytes"; + +struct Fixture { + address: SocketAddr, + task: JoinHandle, +} + +impl Fixture { + fn start() -> Self { + let listener = TcpListener::bind("127.0.0.1:0").expect("bind fixture"); + listener + .set_nonblocking(true) + .expect("make fixture accept bounded"); + let address = listener.local_addr().expect("fixture address"); + let task = thread::spawn(move || { + let deadline = Instant::now() + Duration::from_secs(5); + let (mut stream, _) = loop { + match listener.accept() { + Ok(connection) => break connection, + Err(error) if error.kind() == io::ErrorKind::WouldBlock => { + assert!(Instant::now() < deadline, "fixture accept timed out"); + thread::sleep(Duration::from_millis(2)); + } + Err(error) => panic!("fixture accept failed: {error}"), + } + }; + stream + .set_nonblocking(false) + .expect("make accepted stream blocking"); + stream + .set_read_timeout(Some(Duration::from_secs(3))) + .expect("read timeout"); + stream + .set_write_timeout(Some(Duration::from_secs(3))) + .expect("write timeout"); + let head = read_head(&mut stream); + let response = format!( + "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n", + BODY.len() + ); + stream + .write_all(response.as_bytes()) + .expect("write response headers"); + stream.write_all(BODY).expect("write response body"); + head + }); + Self { address, task } + } + + fn url(&self, path: &str) -> String { + format!("http://{}{path}", self.address) + } + + fn finish(self) -> String { + let deadline = Instant::now() + Duration::from_secs(8); + while !self.task.is_finished() { + assert!(Instant::now() < deadline, "fixture finished"); + thread::sleep(Duration::from_millis(2)); + } + self.task.join().expect("fixture joined") + } +} + +fn read_head(stream: &mut TcpStream) -> String { + let mut bytes = Vec::new(); + let mut buffer = [0u8; 1024]; + while bytes.len() < 16 * 1024 { + let read = stream.read(&mut buffer).expect("read request"); + if read == 0 { + break; + } + bytes.extend_from_slice(&buffer[..read]); + if bytes.windows(4).any(|window| window == b"\r\n\r\n") { + break; + } + } + String::from_utf8(bytes).expect("request head is UTF-8") +} + +fn revision(data_root: &Path) -> u64 { + let output = run_cli(data_root, &["workspace", "status"]); + assert_success(&output); + json_output(&output)["revision"].as_u64().expect("revision") +} + +#[test] +fn a_trusted_fetch_writes_a_private_cache_and_is_audited() { + // Given a registered workspace with task_network and a declared loopback + // registry fixture. + let fixture = Fixture::start(); + let temporary = TempDir::new().expect("temporary directory"); + let data_root = temporary.path().join("data"); + let development_root = temporary.path().join("dev"); + let workspace = development_root.join("work"); + fs::create_dir_all(&workspace).expect("workspace"); + let output = run_cli( + &data_root, + &[ + "workspace", + "set-root", + path_arg(&development_root), + "--revision", + "0", + ], + ); + assert_success(&output); + let initial_revision = json_output(&output)["revision"].as_u64().expect("revision"); + let output = run_cli( + &data_root, + &[ + "workspace", + "register", + path_arg(&workspace), + "--revision", + &initial_revision.to_string(), + ], + ); + assert_success(&output); + let id = json_output(&output)["registration_id"] + .as_str() + .expect("workspace id") + .to_owned(); + let output = run_cli( + &data_root, + &[ + "workspace", + "permissions", + &id, + "--task-network", + "true", + "--revision", + &revision(&data_root).to_string(), + ], + ); + assert_success(&output); + let output = run_cli( + &data_root, + &[ + "workspace", + "package-profile-add", + PROFILE, + "--registry", + &format!("http://{}/fixtures/", fixture.address), + "--revision", + &revision(&data_root).to_string(), + ], + ); + assert_success(&output); + + // When the operator fetches a declared package URL. + let url = fixture.url("/fixtures/pkg.bin"); + let output = run_cli( + &data_root, + &[ + "packages", + "fetch", + &id, + "--profile", + PROFILE, + "--url", + &url, + "--name", + "pkg.bin", + ], + ); + assert_success(&output); + + // Then the report and private cache match the response, and the audit + // records the fetch without the URL text. + let report = json_output(&output)["fetch"].clone(); + assert_eq!(report["bytes"], BODY.len()); + assert_eq!(report["status"], 200); + assert_eq!(report["profile_name"], PROFILE); + let cache = data_root.join("package-cache").join(&id).join("pkg.bin"); + assert_eq!(fs::read(&cache).expect("cache file"), BODY); + let head = fixture.finish(); + assert!(head.starts_with("GET /fixtures/pkg.bin "), "{head}"); + let audit = run_cli(&data_root, &["workspace", "audit", "--limit", "100"]); + assert_success(&audit); + let audit = serde_json::to_string(&json_output(&audit)).expect("audit JSON"); + assert!(audit.contains("package_fetch_started"), "{audit}"); + assert!(audit.contains("package_fetch_finished"), "{audit}"); + assert!( + !audit.contains(&url), + "the request URL was recorded: {audit}" + ); + + // Then invalid bounds are configuration errors and an unknown profile is + // a package error; neither reaches the network. + for options in [ + ["--max-bytes", "0"], + ["--max-bytes", "1073741825"], + ["--timeout-secs", "0"], + ["--timeout-secs", "601"], + ] { + let output = run_cli( + &data_root, + &[ + "packages", + "fetch", + &id, + "--profile", + PROFILE, + "--url", + &url, + "--name", + "other.bin", + options[0], + options[1], + ], + ); + assert_error_code(&output, "configuration"); + } + let output = run_cli( + &data_root, + &[ + "packages", + "fetch", + &id, + "--profile", + "missing", + "--url", + &url, + "--name", + "other.bin", + ], + ); + assert_error_code(&output, "packages"); +} diff --git a/crates/omgcode-core/src/control.rs b/crates/omgcode-core/src/control.rs index c917794..866d149 100644 --- a/crates/omgcode-core/src/control.rs +++ b/crates/omgcode-core/src/control.rs @@ -33,8 +33,10 @@ pub use container::{ /// Whether this platform can record and apply container grants. pub use omgcode_platform::container::CONTAINER_GRANTS_SUPPORTED; pub use package::{ - MAX_PACKAGE_ORIGIN_BYTES, MAX_PACKAGE_ORIGINS, MAX_PACKAGE_PROFILES, PackageOrigin, + MAX_PACKAGE_ORIGIN_BYTES, MAX_PACKAGE_ORIGINS, MAX_PACKAGE_OUTPUT_BYTES, MAX_PACKAGE_PROFILES, + PackageFetchFailure, PackageFetchFinish, PackageFetchOutcome, PackageFetchStart, PackageOrigin, PackageProfile, PackageProfileDeclaration, PackageProfileStatus, PackageScheme, parse_origin, + valid_output_name, }; pub use profile::{ MAX_PROFILE_NAME_CHARS, MAX_PROFILE_PATH_ENTRIES, MAX_PROFILE_ROOTS, MAX_PROFILE_VARIABLES, @@ -277,6 +279,12 @@ enum Action { PackageProfileRemoved { profile_id: Uuid, }, + PackageFetchStarted { + start: PackageFetchStart, + }, + PackageFetchFinished { + finish: PackageFetchFinish, + }, } /// One persisted settings/audit event, never prompts or dedicated credential fields. @@ -847,6 +855,8 @@ impl ControlStore { | Action::ContainerGrantApplied { .. } | Action::ContainerRevokeRequested { .. } | Action::ContainerGrantRevoked { .. } + | Action::PackageFetchStarted { .. } + | Action::PackageFetchFinished { .. } ); let revision = if configuration_change { state @@ -933,7 +943,10 @@ impl ControlStore { Action::ProfileAdded { .. } | Action::ProfileRemoved { .. } => { profile::apply(state, &entry.action, revision)?; } - Action::PackageProfileAdded { .. } | Action::PackageProfileRemoved { .. } => { + Action::PackageProfileAdded { .. } + | Action::PackageProfileRemoved { .. } + | Action::PackageFetchStarted { .. } + | Action::PackageFetchFinished { .. } => { package::apply(state, &entry.action, revision)?; } } diff --git a/crates/omgcode-core/src/control/package.rs b/crates/omgcode-core/src/control/package.rs index 94165ea..113a0ee 100644 --- a/crates/omgcode-core/src/control/package.rs +++ b/crates/omgcode-core/src/control/package.rs @@ -13,6 +13,7 @@ use serde::{Deserialize, Serialize}; use uuid::Uuid; use super::{Action, ControlError, ControlSnapshot, ControlStore, valid_profile_name, valid_uuid}; +use crate::policy::WorkspaceId; /// Most recorded package-network profiles. pub const MAX_PACKAGE_PROFILES: usize = 32; @@ -24,6 +25,8 @@ pub const MAX_PACKAGE_ORIGIN_BYTES: usize = 2048; pub const MAX_PACKAGE_HOST_BYTES: usize = 253; /// Longest registry path prefix, in bytes. pub const MAX_PACKAGE_PATH_BYTES: usize = 1024; +/// Longest package cache output name, in bytes. +pub const MAX_PACKAGE_OUTPUT_BYTES: usize = 128; /// The scheme a registry origin uses. #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] @@ -134,6 +137,71 @@ pub struct PackageProfileDeclaration { pub origins: Vec, } +/// The audit intent recorded before a trusted package fetch starts. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct PackageFetchStart { + /// Durable fetch identifier, used to pair the outcome. + pub fetch_id: Uuid, + /// The workspace whose private cache receives the file. + #[serde(deserialize_with = "super::deserialize_workspace_id")] + pub workspace_id: WorkspaceId, + /// The selected package-network profile. + pub profile_id: Uuid, + pub profile_name: String, + pub profile_revision: u64, + /// SHA-256 of the exact request URL. The URL text is not recorded. + pub url_sha256: String, + /// The cache file name. + pub output_name: String, + /// The greatest response body accepted. + pub max_bytes: u64, + /// The request deadline. + pub timeout_ms: u64, +} + +/// The audit outcome of a trusted package fetch. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct PackageFetchFinish { + pub fetch_id: Uuid, + pub outcome: PackageFetchOutcome, + /// The final HTTP status, when a response was received. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub status: Option, + /// Bytes written to the cache; zero unless the fetch completed. + pub bytes: u64, + /// SHA-256 of the cached bytes, when the fetch completed. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub sha256: Option, +} + +/// How a trusted package fetch ended. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)] +pub enum PackageFetchOutcome { + /// The file was written and synced to the cache. + Fetched, + /// The fetch failed after its intent was recorded. + Failed { reason: PackageFetchFailure }, +} + +/// A controlled package-fetch failure recorded in the outcome. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum PackageFetchFailure { + /// The request could not be sent or read. + Transport, + /// The registry answered with a non-success status. + Status, + /// The body passed the size limit. + TooLarge, + /// The cache file could not be created, written, or published. + Cache, + /// The file was written, but its directory entry could not be synced. + Sync, +} + /// Parse one registry origin. /// /// The origin must be an absolute `https` URL. `http` is accepted only for @@ -279,6 +347,70 @@ impl ControlStore { )?; Ok(profile_id) } + + /// Record the intent of a trusted package fetch. This preserves the + /// settings revision; the fetch is audit, not configuration. + pub fn record_package_fetch_started( + &mut self, + start: PackageFetchStart, + ) -> Result<(), ControlError> { + validate_fetch_start(&start)?; + self.append(Action::PackageFetchStarted { start }, self.revision()) + } + + /// Record the outcome of a trusted package fetch. This preserves the + /// settings revision. + pub fn record_package_fetch_finished( + &mut self, + finish: PackageFetchFinish, + ) -> Result<(), ControlError> { + validate_fetch_finish(&finish)?; + self.append(Action::PackageFetchFinished { finish }, self.revision()) + } +} + +/// Whether `name` is a safe single cache file name. It is ASCII letters, +/// digits, `.`, `-`, or `_`, starts and ends with a letter or digit, and is not +/// a reserved Windows device name. +pub fn valid_output_name(name: &str) -> bool { + if name.is_empty() || name.len() > MAX_PACKAGE_OUTPUT_BYTES { + return false; + } + let bytes = name.as_bytes(); + if !bytes.first().is_some_and(u8::is_ascii_alphanumeric) + || !bytes.last().is_some_and(u8::is_ascii_alphanumeric) + || !bytes + .iter() + .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_')) + { + return false; + } + let stem = name.split('.').next().unwrap_or("").to_ascii_uppercase(); + !matches!( + stem.as_str(), + "CON" + | "PRN" + | "AUX" + | "NUL" + | "COM1" + | "COM2" + | "COM3" + | "COM4" + | "COM5" + | "COM6" + | "COM7" + | "COM8" + | "COM9" + | "LPT1" + | "LPT2" + | "LPT3" + | "LPT4" + | "LPT5" + | "LPT6" + | "LPT7" + | "LPT8" + | "LPT9" + ) } /// Validate and apply one package-profile action during replay or append @@ -317,11 +449,68 @@ pub(super) fn apply( ))?; state.package_profiles.remove(index); } + Action::PackageFetchStarted { start } => { + validate_fetch_start(start) + .map_err(|_| ControlError::Invalid("invalid package fetch start"))?; + } + Action::PackageFetchFinished { finish } => { + validate_fetch_finish(finish) + .map_err(|_| ControlError::Invalid("invalid package fetch finish"))?; + } _ => {} } Ok(()) } +fn validate_fetch_start(start: &PackageFetchStart) -> Result<(), ControlError> { + if !valid_uuid(start.fetch_id) + || !valid_uuid(start.profile_id) + || !valid_profile_name(&start.profile_name) + || start.profile_revision == 0 + || !valid_digest(&start.url_sha256) + || !valid_output_name(&start.output_name) + || start.max_bytes == 0 + || start.timeout_ms == 0 + { + return Err(refused("a package fetch start is invalid")); + } + Ok(()) +} + +fn validate_fetch_finish(finish: &PackageFetchFinish) -> Result<(), ControlError> { + if !valid_uuid(finish.fetch_id) + || finish + .status + .is_some_and(|status| !(100..=599).contains(&status)) + { + return Err(refused("a package fetch outcome is invalid")); + } + match finish.outcome { + PackageFetchOutcome::Fetched => { + if finish + .sha256 + .as_deref() + .is_none_or(|digest| !valid_digest(digest)) + { + return Err(refused("a fetched outcome needs a valid content digest")); + } + } + PackageFetchOutcome::Failed { .. } => { + if finish.bytes != 0 || finish.sha256.is_some() { + return Err(refused("a failed fetch records no cached bytes")); + } + } + } + Ok(()) +} + +fn valid_digest(value: &str) -> bool { + value.len() == 64 + && value + .bytes() + .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()) +} + /// Check everything about a profile that needs no network or filesystem. fn validate_profile(profile: &PackageProfile) -> Result<(), ControlError> { if !valid_uuid(profile.id) || !valid_profile_name(&profile.name) { diff --git a/crates/omgcode-core/src/lib.rs b/crates/omgcode-core/src/lib.rs index 721e1ef..17a30de 100644 --- a/crates/omgcode-core/src/lib.rs +++ b/crates/omgcode-core/src/lib.rs @@ -5,6 +5,7 @@ pub mod control; pub mod edit; mod file_audit; pub mod files; +pub mod packages; pub mod policy; pub mod prompt; pub mod provider; diff --git a/crates/omgcode-core/src/packages.rs b/crates/omgcode-core/src/packages.rs new file mode 100644 index 0000000..3a382e1 --- /dev/null +++ b/crates/omgcode-core/src/packages.rs @@ -0,0 +1,490 @@ +//! Trusted allowlisted package fetch. +//! +//! `packages fetch` is an operator command, never a model tool. It contacts +//! only an origin declared in a recorded package-network profile, refuses +//! redirects, and writes one bounded response into a private per-workspace +//! cache. The confined run still has no network access; exposing the cache to +//! it is a separate increment. +//! +//! The request URL text is not recorded. The control journal records the +//! intent and outcome with a URL digest, the profile, the cache name, byte +//! count, and content digest. A failed or abandoned fetch leaves its start +//! record; no automatic retry follows. See `docs/execution.md` and ADR-0035. + +use std::fmt::Write as _; +use std::fs::{self, OpenOptions}; +use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; +use std::thread; +use std::time::{Duration, Instant}; + +use reqwest::Url; +use reqwest::blocking::Client; +use reqwest::redirect::Policy; +use serde::Serialize; +use sha2::{Digest, Sha256}; +use thiserror::Error; +use uuid::Uuid; + +use crate::control::{ + ControlError, ControlStore, PackageFetchFailure, PackageFetchFinish, PackageFetchOutcome, + PackageFetchStart, PackageProfile, valid_output_name, +}; +use crate::policy::WorkspaceId; +use crate::session::NativePath; +use crate::storage; + +/// Default greatest response body accepted. +pub const DEFAULT_MAX_FETCH_BYTES: u64 = 64 * 1024 * 1024; +/// Largest accepted response body. +pub const MAX_FETCH_BYTES: u64 = 1024 * 1024 * 1024; +/// Default request deadline. +pub const DEFAULT_FETCH_TIMEOUT: Duration = Duration::from_secs(60); +/// Longest accepted request deadline. +pub const MAX_FETCH_TIMEOUT: Duration = Duration::from_secs(600); +/// Longest request URL accepted. +pub const MAX_FETCH_URL_BYTES: usize = 4096; + +const CONNECT_TIMEOUT: Duration = Duration::from_secs(10); +const CONTROL_WAIT: Duration = Duration::from_secs(10); +const CONTROL_POLL: Duration = Duration::from_millis(20); +const READ_CHUNK: usize = 64 * 1024; + +/// One requested package fetch. Every field is operator input, not a grant. +#[derive(Clone, Debug)] +pub struct FetchRequest { + /// The registered workspace whose private cache receives the file. + pub workspace_id: WorkspaceId, + /// The recorded package-network profile name. + pub profile: String, + /// The absolute registry URL. + pub url: String, + /// The cache file name. + pub name: String, + /// Greatest response body accepted. + pub max_bytes: u64, + /// Request deadline. + pub timeout: Duration, +} + +/// The receipt for one completed fetch. It never contains the URL text. +#[derive(Clone, Debug, Serialize)] +pub struct FetchReport { + /// Durable audit identifier. + pub fetch_id: Uuid, + /// The selected profile. + pub profile_id: Uuid, + pub profile_name: String, + pub profile_revision: u64, + /// SHA-256 of the request URL. + pub url_sha256: String, + /// The private cache file. + pub output: NativePath, + /// Bytes written. + pub bytes: u64, + /// SHA-256 of the cached bytes. + pub sha256: String, + /// The final HTTP status. + pub status: u16, +} + +/// A controlled package-fetch failure. +#[derive(Debug, Error)] +pub enum FetchError { + /// A check or bound refused the request; nothing was recorded. + #[error("package fetch refused: {0}")] + Refused(&'static str), + /// The control journal could not be read or written. + #[error("workspace control failed: {0}")] + Control(#[from] ControlError), + /// The request could not be sent or the connection failed. + #[error("the registry request failed: {0}")] + Transport(#[source] reqwest::Error), + /// The response body could not be read. + #[error("the response body could not be read: {0}")] + Body(#[source] io::Error), + /// The registry returned a non-success status. + #[error("the registry returned HTTP status {0}")] + Status(u16), + /// The response body passed the size limit. + #[error("the package is larger than the allowed {0} bytes")] + TooLarge(u64), + /// The cache directory or file could not be written or published. + #[error("the package cache could not be written: {0}")] + Cache(#[source] io::Error), + /// The cache file already exists; fetch it under a new name. + #[error("the cache file {0} already exists")] + AlreadyCached(String), + /// The file was published, but its outcome could not be recorded. + #[error("the package was fetched, but its outcome could not be recorded: {source}")] + OutcomeNotRecorded { + report: Box, + #[source] + source: ControlError, + }, + /// The fetch failed, and recording the failure also failed. + #[error("{failure}; its outcome could not be recorded: {audit}")] + FailureAndAudit { + #[source] + failure: Box, + audit: ControlError, + }, +} + +struct FailedFetch { + error: FetchError, + reason: PackageFetchFailure, + status: Option, +} + +/// Fetch one allowed URL into the workspace's private cache. +/// +/// The request must use a recorded package profile, the workspace must enable +/// `task_network`, the URL must match one declared origin and path prefix, and +/// no redirect is followed. A successful response is bounded, hashed, written +/// to a private file, synced, and published under a new name. +/// +/// # Errors +/// +/// Returns a typed failure. A request that passed the checks is recorded as +/// started before the network call; a later failure is recorded as a failed +/// outcome unless the journal itself is unavailable. +pub fn fetch(data_root: &Path, request: &FetchRequest) -> Result { + validate_request(request)?; + let control = open_control(data_root)?; + let registration = control + .workspace(request.workspace_id) + .ok_or(FetchError::Refused("the workspace is not registered"))?; + if !registration.permissions().task_network { + return Err(FetchError::Refused( + "the workspace task_network preference is disabled", + )); + } + let status = control + .package_profile(&request.profile) + .ok_or(FetchError::Refused( + "no recorded package-network profile has this name", + ))?; + let profile = status.profile(); + let profile_revision = status.revision(); + let url = + Url::parse(&request.url).map_err(|_| FetchError::Refused("the URL must be absolute"))?; + matching_origin(profile, &url)?; + let cache = cache_directory(data_root, request.workspace_id); + storage::create_private_directories(&cache) + .map_err(|error| FetchError::Cache(io::Error::other(error.to_string())))?; + let final_path = cache.join(&request.name); + match fs::symlink_metadata(&final_path) { + Ok(_) => return Err(FetchError::AlreadyCached(request.name.clone())), + Err(error) if error.kind() == io::ErrorKind::NotFound => {} + Err(error) => return Err(FetchError::Cache(error)), + } + + let start = PackageFetchStart { + fetch_id: Uuid::new_v4(), + workspace_id: request.workspace_id, + profile_id: profile.id(), + profile_name: profile.name().to_owned(), + profile_revision, + url_sha256: hex(&Sha256::digest(request.url.as_bytes())), + output_name: request.name.clone(), + max_bytes: request.max_bytes, + timeout_ms: millis(request.timeout), + }; + let mut control = control; + control.record_package_fetch_started(start.clone())?; + drop(control); + + let fetch_id = start.fetch_id; + match perform(&start, &url, &cache, &final_path) { + Ok((report, http_status)) => { + let finish = PackageFetchFinish { + fetch_id, + outcome: PackageFetchOutcome::Fetched, + status: Some(http_status), + bytes: report.bytes, + sha256: Some(report.sha256.clone()), + }; + let recorded = open_control(data_root) + .and_then(|mut store| store.record_package_fetch_finished(finish)); + if let Err(source) = recorded { + return Err(FetchError::OutcomeNotRecorded { + report: Box::new(report), + source, + }); + } + Ok(report) + } + Err(failed) => { + let finish = PackageFetchFinish { + fetch_id, + outcome: PackageFetchOutcome::Failed { + reason: failed.reason, + }, + status: failed.status, + bytes: 0, + sha256: None, + }; + let recorded = open_control(data_root) + .and_then(|mut store| store.record_package_fetch_finished(finish)); + if let Err(audit) = recorded { + return Err(FetchError::FailureAndAudit { + failure: Box::new(failed.error), + audit, + }); + } + Err(failed.error) + } + } +} + +fn validate_request(request: &FetchRequest) -> Result<(), FetchError> { + if request.max_bytes == 0 || request.max_bytes > MAX_FETCH_BYTES { + return Err(FetchError::Refused( + "the byte limit must be between 1 and 1073741824", + )); + } + if request.timeout < Duration::from_secs(1) || request.timeout > MAX_FETCH_TIMEOUT { + return Err(FetchError::Refused( + "the timeout must be between 1 and 600 seconds", + )); + } + if request.url.len() > MAX_FETCH_URL_BYTES { + return Err(FetchError::Refused("the URL is too long")); + } + if !valid_output_name(&request.name) { + return Err(FetchError::Refused("the cache name is invalid")); + } + Ok(()) +} + +fn cache_directory(data_root: &Path, workspace_id: WorkspaceId) -> PathBuf { + data_root + .join("package-cache") + .join(workspace_id.to_string()) +} + +/// Require the URL to match a declared origin and path prefix, with no +/// credentials, query, or fragment. +fn matching_origin(profile: &PackageProfile, url: &Url) -> Result<(), FetchError> { + if !url.username().is_empty() || url.password().is_some() { + return Err(FetchError::Refused("the URL must not contain credentials")); + } + if url.query().is_some() { + return Err(FetchError::Refused("the URL must not contain a query")); + } + if url.fragment().is_some() { + return Err(FetchError::Refused("the URL must not contain a fragment")); + } + let host = url + .host_str() + .ok_or(FetchError::Refused("the URL needs a host"))?; + let port = url + .port_or_known_default() + .ok_or(FetchError::Refused("the URL needs a port"))?; + let path = url.path(); + let matched = profile.origins().iter().any(|origin| { + origin.scheme().as_str() == url.scheme() + && origin.host().eq_ignore_ascii_case(host) + && origin.port() == port + && path.starts_with(origin.path_prefix()) + }); + if !matched { + return Err(FetchError::Refused( + "the URL is not under a declared registry origin and path", + )); + } + Ok(()) +} + +fn perform( + start: &PackageFetchStart, + url: &Url, + cache: &Path, + final_path: &Path, +) -> Result<(FetchReport, u16), FailedFetch> { + let timeout = Duration::from_millis(start.timeout_ms); + let client = Client::builder() + .no_proxy() + .redirect(Policy::none()) + .retry(reqwest::retry::never()) + .connect_timeout(CONNECT_TIMEOUT.min(timeout)) + .timeout(timeout) + .build() + .map_err(|error| FailedFetch { + error: FetchError::Transport(error), + reason: PackageFetchFailure::Transport, + status: None, + })?; + let mut response = client + .get(url.as_str()) + .send() + .map_err(|error| FailedFetch { + error: FetchError::Transport(error), + reason: PackageFetchFailure::Transport, + status: None, + })?; + let http_status = response.status().as_u16(); + if !response.status().is_success() { + return Err(FailedFetch { + error: FetchError::Status(http_status), + reason: PackageFetchFailure::Status, + status: Some(http_status), + }); + } + + let temporary = cache.join(format!(".{}.partial-{}", start.output_name, start.fetch_id)); + let mut file = open_cache_file(&temporary).map_err(|error| FailedFetch { + error: FetchError::Cache(error), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + })?; + let mut hasher = Sha256::new(); + let mut bytes = 0u64; + let mut buffer = vec![0u8; READ_CHUNK]; + loop { + let read = match response.read(&mut buffer) { + Ok(0) => break, + Ok(read) => read, + Err(error) => { + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::Body(error), + reason: PackageFetchFailure::Transport, + status: Some(http_status), + }); + } + }; + bytes = bytes.saturating_add(u64::try_from(read).unwrap_or(u64::MAX)); + if bytes > start.max_bytes { + drop(file); + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::TooLarge(start.max_bytes), + reason: PackageFetchFailure::TooLarge, + status: Some(http_status), + }); + } + if let Err(error) = file.write_all(&buffer[..read]) { + drop(file); + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::Cache(error), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + }); + } + hasher.update(&buffer[..read]); + } + if let Err(error) = file.sync_all() { + drop(file); + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::Cache(error), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + }); + } + drop(file); + + // The cache is private to the user; a same-user writer can already change + // it. Refuse a name that appeared after the pre-check, and publish with a + // rename. No power-loss claim is made for this cache. + match fs::symlink_metadata(final_path) { + Ok(_) => { + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::AlreadyCached(start.output_name.clone()), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + }); + } + Err(error) if error.kind() == io::ErrorKind::NotFound => {} + Err(error) => { + let _ = fs::remove_file(&temporary); + return Err(FailedFetch { + error: FetchError::Cache(error), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + }); + } + } + if let Err(error) = fs::rename(&temporary, final_path) { + let _ = fs::remove_file(&temporary); + let already = fs::symlink_metadata(final_path).is_ok(); + let error = if already { + FetchError::AlreadyCached(start.output_name.clone()) + } else { + FetchError::Cache(error) + }; + return Err(FailedFetch { + error, + reason: PackageFetchFailure::Cache, + status: Some(http_status), + }); + } + + Ok(( + FetchReport { + fetch_id: start.fetch_id, + profile_id: start.profile_id, + profile_name: start.profile_name.clone(), + profile_revision: start.profile_revision, + url_sha256: start.url_sha256.clone(), + output: NativePath::from_path(final_path).map_err(|error| FailedFetch { + error: FetchError::Cache(io::Error::other(error.to_string())), + reason: PackageFetchFailure::Cache, + status: Some(http_status), + })?, + bytes, + sha256: hex(&hasher.finalize()), + status: http_status, + }, + http_status, + )) +} + +fn open_cache_file(path: &Path) -> io::Result { + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + options.open(path) +} + +/// Open existing settings, waiting briefly for another command's lock. +fn open_control(data_root: &Path) -> Result { + let until = Instant::now() + CONTROL_WAIT; + loop { + match ControlStore::open_existing(data_root) { + Ok(Some(store)) => return Ok(store), + Ok(None) => { + return Err(ControlError::Io(io::Error::new( + io::ErrorKind::NotFound, + "workspace control is not initialized", + ))); + } + Err(ControlError::Busy) if Instant::now() < until => thread::sleep(CONTROL_POLL), + Err(error) => return Err(error), + } + } +} + +fn millis(duration: Duration) -> u64 { + u64::try_from(duration.as_millis()).unwrap_or(u64::MAX) +} + +fn hex(bytes: &[u8]) -> String { + let mut text = String::with_capacity(bytes.len() * 2); + for byte in bytes { + // Writing to a `String` cannot fail. + let _ = write!(&mut text, "{byte:02x}"); + } + text +} + +#[cfg(test)] +mod tests; diff --git a/crates/omgcode-core/src/packages/tests.rs b/crates/omgcode-core/src/packages/tests.rs new file mode 100644 index 0000000..f412aca --- /dev/null +++ b/crates/omgcode-core/src/packages/tests.rs @@ -0,0 +1,321 @@ +use super::*; +use std::net::{SocketAddr, TcpListener, TcpStream}; +use std::thread::{self, JoinHandle}; +use std::time::{Duration, Instant}; + +use crate::control::{ControlStore, PackageProfileDeclaration}; +use crate::policy::{PermissionSet, WorkspaceId}; + +const PROFILE: &str = "registries"; +const MAX_REQUEST_HEADER_BYTES: usize = 16 * 1024; + +/// One bounded local HTTP response. +struct Fixture { + address: SocketAddr, + task: JoinHandle<(String, usize)>, +} + +impl Fixture { + fn start(status: u16, body: Vec, headers: &str) -> Self { + let listener = TcpListener::bind("127.0.0.1:0").expect("bind fixture"); + listener + .set_nonblocking(true) + .expect("make fixture accept bounded"); + let address = listener.local_addr().expect("fixture address"); + let headers = headers.to_owned(); + let task = thread::spawn(move || { + let deadline = Instant::now() + Duration::from_secs(5); + let (mut stream, _) = loop { + match listener.accept() { + Ok(connection) => break connection, + Err(error) if error.kind() == io::ErrorKind::WouldBlock => { + assert!(Instant::now() < deadline, "fixture accept timed out"); + thread::sleep(Duration::from_millis(2)); + } + Err(error) => panic!("fixture accept failed: {error}"), + } + }; + stream + .set_nonblocking(false) + .expect("make accepted stream blocking"); + stream + .set_read_timeout(Some(Duration::from_secs(3))) + .expect("read timeout"); + stream + .set_write_timeout(Some(Duration::from_secs(3))) + .expect("write timeout"); + let head = read_head(&mut stream); + let response = format!( + "HTTP/1.1 {status} OK\r\nContent-Length: {}\r\nConnection: close\r\n{headers}\r\n", + body.len() + ); + stream + .write_all(response.as_bytes()) + .expect("write response headers"); + stream.write_all(&body).expect("write response body"); + (head, body.len()) + }); + Self { address, task } + } + + fn url(&self, path: &str) -> String { + format!("http://{}{path}", self.address) + } + + fn finish(self) -> String { + join_bounded(self.task) + } +} + +fn read_head(stream: &mut TcpStream) -> String { + let mut bytes = Vec::new(); + let mut buffer = [0u8; 1024]; + while bytes.len() < MAX_REQUEST_HEADER_BYTES { + let read = stream.read(&mut buffer).expect("read request"); + if read == 0 { + break; + } + bytes.extend_from_slice(&buffer[..read]); + if bytes.windows(4).any(|window| window == b"\r\n\r\n") { + break; + } + } + String::from_utf8(bytes).expect("request head is UTF-8") +} + +fn join_bounded(task: JoinHandle<(String, usize)>) -> String { + let deadline = Instant::now() + Duration::from_secs(8); + while !task.is_finished() { + assert!(Instant::now() < deadline, "fixture finished"); + thread::sleep(Duration::from_millis(2)); + } + let (head, _) = task.join().expect("fixture joined"); + head +} + +/// A workspace with `task_network`, a package profile, and the control data. +struct Scene { + _directory: tempfile::TempDir, + data: PathBuf, + workspace_id: WorkspaceId, +} + +impl Scene { + fn new(origins: &[String]) -> Self { + let directory = tempfile::tempdir().expect("temporary directory"); + let data = directory.path().join("data"); + let root = directory.path().join("dev"); + let workspace = root.join("workspace"); + fs::create_dir_all(&workspace).expect("workspace"); + let mut store = ControlStore::open(&data).expect("store"); + store.set_development_root(&root, 0).expect("root"); + let workspace_id = store + .register_workspace(&workspace, store.revision()) + .expect("register") + .id(); + let permissions = PermissionSet { + task_network: true, + ..PermissionSet::default() + }; + store + .set_permissions(workspace_id, permissions, store.revision()) + .expect("permissions"); + store + .add_package_profile( + &PackageProfileDeclaration { + name: PROFILE.into(), + origins: origins.to_vec(), + }, + store.revision(), + ) + .expect("profile"); + Self { + _directory: directory, + data, + workspace_id, + } + } + + fn request(&self, url: String, name: &str, max_bytes: u64) -> FetchRequest { + FetchRequest { + workspace_id: self.workspace_id, + profile: PROFILE.into(), + url, + name: name.into(), + max_bytes, + timeout: Duration::from_secs(10), + } + } + + fn cache_file(&self, name: &str) -> PathBuf { + self.data + .join("package-cache") + .join(self.workspace_id.to_string()) + .join(name) + } + + fn audit_text(&self) -> String { + let store = ControlStore::open_existing(&self.data) + .expect("open") + .expect("store"); + serde_json::to_string(&store.audit(100).expect("audit")).expect("audit JSON") + } +} + +fn hex_digest(bytes: &[u8]) -> String { + hex(&Sha256::digest(bytes)) +} + +#[test] +fn a_declared_origin_is_fetched_and_audited() { + let body = b"package-bytes".to_vec(); + let fixture = Fixture::start(200, body.clone(), ""); + let scene = Scene::new(&[format!("http://{}/fixtures/", fixture.address)]); + let url = fixture.url("/fixtures/pkg.bin"); + let report = fetch(&scene.data, &scene.request(url.clone(), "pkg.bin", 1024)) + .expect("fetch allowed origin"); + assert_eq!(report.bytes, body.len() as u64); + assert_eq!(report.sha256, hex_digest(&body)); + assert_eq!(report.status, 200); + assert_eq!(report.profile_name, PROFILE); + assert_eq!(report.url_sha256, hex_digest(url.as_bytes())); + assert_eq!( + fs::read(scene.cache_file("pkg.bin")).expect("cache file"), + body + ); + let head = fixture.finish(); + assert!(head.starts_with("GET /fixtures/pkg.bin "), "{head}"); + + let audit = scene.audit_text(); + assert!(audit.contains("package_fetch_started"), "{audit}"); + assert!(audit.contains("package_fetch_finished"), "{audit}"); + assert!( + !audit.contains(&url), + "the request URL was recorded: {audit}" + ); + assert!(audit.contains(&report.url_sha256), "{audit}"); + assert!(audit.contains("\"kind\":\"fetched\""), "{audit}"); +} + +#[test] +fn an_undeclared_origin_or_path_is_refused_before_a_request() { + // A closed loopback port stands in for an origin that was not declared. + let scene = Scene::new(&["http://127.0.0.1:9/fixtures/".to_owned()]); + let before = scene.audit_text(); + let error = fetch( + &scene.data, + &scene.request( + "http://127.0.0.1:9/other/pkg.bin".to_owned(), + "pkg.bin", + 1024, + ), + ) + .expect_err("undeclared path"); + assert!(matches!(error, FetchError::Refused(_)), "{error}"); + assert_eq!(scene.audit_text(), before); + assert!(!scene.cache_file("pkg.bin").exists()); + + let error = fetch( + &scene.data, + &scene.request( + "http://127.0.0.1:10/fixtures/pkg.bin".to_owned(), + "pkg.bin", + 1024, + ), + ) + .expect_err("undeclared origin"); + assert!(matches!(error, FetchError::Refused(_)), "{error}"); + assert_eq!(scene.audit_text(), before); +} + +#[test] +fn redirects_are_not_followed() { + let fixture = Fixture::start(302, Vec::new(), "Location: /elsewhere\r\n"); + let scene = Scene::new(&[format!("http://{}/fixtures/", fixture.address)]); + let url = fixture.url("/fixtures/pkg.bin"); + let error = fetch(&scene.data, &scene.request(url, "pkg.bin", 1024)).expect_err("redirect"); + assert!(matches!(error, FetchError::Status(302)), "{error}"); + assert!(!scene.cache_file("pkg.bin").exists()); + let audit = scene.audit_text(); + assert!(audit.contains("\"kind\":\"failed\""), "{audit}"); + assert!(audit.contains("status"), "{audit}"); +} + +#[test] +fn the_size_limit_is_enforced_and_leaves_no_cache_file() { + let fixture = Fixture::start(200, b"too-large".to_vec(), ""); + let scene = Scene::new(&[format!("http://{}/fixtures/", fixture.address)]); + let url = fixture.url("/fixtures/pkg.bin"); + let error = fetch(&scene.data, &scene.request(url, "pkg.bin", 4)).expect_err("oversize"); + assert!(matches!(error, FetchError::TooLarge(4)), "{error}"); + assert!(!scene.cache_file("pkg.bin").exists()); + let listing: Vec<_> = fs::read_dir(scene.cache_file("pkg.bin").parent().expect("cache")) + .expect("cache listing") + .collect(); + assert!(listing.is_empty(), "a partial cache file remained"); +} + +#[test] +fn an_existing_cache_file_is_not_overwritten() { + let body = b"first".to_vec(); + let fixture = Fixture::start(200, body.clone(), ""); + let scene = Scene::new(&[format!("http://{}/fixtures/", fixture.address)]); + let url = fixture.url("/fixtures/pkg.bin"); + fetch(&scene.data, &scene.request(url.clone(), "pkg.bin", 1024)).expect("first fetch"); + let before = scene.audit_text(); + let error = + fetch(&scene.data, &scene.request(url, "pkg.bin", 1024)).expect_err("existing cache file"); + assert!( + matches!(&error, FetchError::AlreadyCached(name) if name == "pkg.bin"), + "{error}" + ); + assert_eq!(fs::read(scene.cache_file("pkg.bin")).expect("cache"), body); + assert_eq!(scene.audit_text(), before, "the refused fetch was recorded"); +} + +#[test] +fn task_network_is_required_and_bad_names_are_refused() { + let scene = Scene::new(&["http://127.0.0.1:9/fixtures/".to_owned()]); + let mut store = ControlStore::open(&scene.data).expect("store"); + store + .set_permissions( + scene.workspace_id, + PermissionSet::default(), + store.revision(), + ) + .expect("disable task_network"); + drop(store); + let before = scene.audit_text(); + let error = fetch( + &scene.data, + &scene.request( + "http://127.0.0.1:9/fixtures/pkg.bin".to_owned(), + "pkg.bin", + 1024, + ), + ) + .expect_err("task_network disabled"); + assert!(matches!(error, FetchError::Refused(_)), "{error}"); + assert_eq!(scene.audit_text(), before); + + let mut store = ControlStore::open(&scene.data).expect("store"); + store + .set_permissions( + scene.workspace_id, + PermissionSet { + task_network: true, + ..PermissionSet::default() + }, + store.revision(), + ) + .expect("enable task_network"); + drop(store); + for name in ["../pkg", "CON", ".hidden", "pkg/child"] { + let error = fetch( + &scene.data, + &scene.request("http://127.0.0.1:9/fixtures/pkg.bin".to_owned(), name, 1024), + ) + .expect_err("bad cache name"); + assert!(matches!(error, FetchError::Refused(_)), "{name}: {error}"); + } +} diff --git a/docs/README.md b/docs/README.md index ae352cd..f6041ef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -87,7 +87,9 @@ command uses native confinement that was tested on one Windows build and one Linux kernel only. Every trusted run has memory, process-count, CPU-time, and sampled net disk-growth limits; the disk limit is not a filesystem quota. Package-network profiles are recorded as configuration only (ADR-0034); no run -uses them, and network access remains all-or-nothing. The +uses them, and network access remains all-or-nothing. The trusted +`packages fetch` command downloads from declared origins into a private cache; +the run does not yet read that cache. The limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed diff --git a/docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md b/docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md new file mode 100644 index 0000000..bab9f40 --- /dev/null +++ b/docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md @@ -0,0 +1,102 @@ +# 0035: Fetch packages through a trusted allowlisted cache + +- Status: Accepted +- Date: 2026-11-13 + +## Context + +[ADR-0034](0034-gate-package-networking-behind-enforceable-destination-control.md) +gates destination-scoped package networking on an enforceable mechanism. The +current primitives cannot filter destinations for a confined tree: +Landlock filters TCP by port, classic seccomp cannot read `sockaddr`, and +AppContainer capabilities cannot name hosts. An advisory proxy is bypassable. + +Version 0.20.0 records operator-declared package-network profiles but no run +accepts one. The next increment is an enforceable download path. + +A trusted host-side fetch is enforceable without a new kernel primitive: the +trusted CLI performs the request in the operator's context, and the confined +run keeps no network access. The cache is private application storage. + +## Decision + +Add the trusted operator command: + +```text +omgcode packages fetch --profile --url + --name [--max-bytes <1-1073741824>] + [--timeout-secs <1-600>] +``` + +Rules: + +- **Caller:** trusted CLI only. No model tool, run, or journal record can + invoke it. The workspace must be registered and its live `task_network` + preference must be enabled. A profile is selected by name and its recorded + revision is audited. +- **Destination:** the URL is absolute and must match a recorded origin's + scheme, host, port, and path prefix. Normal use is `https`; `http` is + accepted only for a loopback test fixture. Credentials, queries, fragments, + and wildcards are refused. Redirects are never followed; a non-2xx response + is a failure. +- **Transport:** TLS uses the operating-system trust store through + `reqwest`'s `native-tls` feature. Certificate validation is never disabled. + The client ignores proxy environment variables and retries nothing. +- **Bounds:** one GET, a deadline of 1 to 600 seconds, and a response body of + 1 byte to 1 GiB. The body is streamed, hashed with SHA-256, and stopped as + soon as it passes the byte limit. +- **Cache:** `/package-cache//`. The name + is one safe file name; directories request 0700 and files 0600 on Unix. A + `.partial-` file is synced and renamed into place. An existing + cache name is never overwritten. The cache makes no power-loss claim; a + failed fetch may leave a partial file that the operator can inspect. +- **Audit:** the control journal records `package_fetch_started` before the + request and `package_fetch_finished` after it. Both preserve the settings + revision. They record the profile identity and revision, a SHA-256 of the + URL (never its text), the cache name, limits, HTTP status, byte count, and + content digest. A failure records a controlled reason. An abandoned fetch + leaves its start record with no finish; nothing retries automatically. +- **Run boundary:** the confined run still has no network access and does not + yet read the cache. Exposing the cache to a run is a separate increment and + needs its own review of read-only confinement and tool configuration. + +## Alternatives considered + +- **Advisory proxy or proxy environment variables.** Rejected: the tree can + connect directly. +- **An OS destination filter or Linux network-namespace relay.** Deferred: + no unprivileged cross-platform primitive; the namespace design needs user + namespaces and is Linux-only. +- **Fetch from inside the confined run.** Rejected: it would restore general + network access without a destination filter. +- **Write the cache into the workspace for immediate tool use.** Rejected for + this increment: the trusted command would bypass the workspace replacement + contract, and a workspace-writable cache is not a protected cache. A + private cache plus a later read-only exposure keeps the boundary visible. +- **A new dedicated package journal.** Rejected for now: the control journal + is already the bounded settings/audit log, and fetch events preserve its + settings revision. A separate journal would add another recovery state + machine without adding authority. + +## Consequences + +- Package downloads have an enforceable allowlisted path, and the run remains + offline. The fetch is not a general host shell or a network relay. +- The cache is not yet available to runs or toolchains. The operator must + inspect or import it until the exposure increment lands. +- Registry credentials are still unsupported. The URL scheme, host, port, and + path are the only authorization; a credential path needs a separate design. +- `reqwest` gains the `native-tls` feature and its dependency tree. TLS uses + the system trust store. The tests use loopback HTTP; they do not qualify a + live HTTPS registry. +- The cache is private to the user. A hostile same-user process can change it, + and the cache is not a conflict-free or power-loss-qualified store. + +## References + +- [Command execution](../execution.md#package-network-profile-contract-only) +- [Development tools](../development-tools.md) +- [Workspace settings](../workspace-permissions.md) +- [Security coding rules](../security-coding-rules.md#provider-traffic-and-tool-calls) +- [Testing standards](../testing-standards.md) +- [ADR-0034](0034-gate-package-networking-behind-enforceable-destination-control.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 02731c9..270a824 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -49,3 +49,4 @@ meaningful alternative does not need an ADR. | [0032: Allow outbound network for trusted runs through task_network](0032-allow-outbound-network-for-trusted-runs-through-task-network.md) | Accepted | 2026-11-13 | | [0033: Bound run disk growth by sampling writable roots](0033-bound-run-disk-growth-by-sampling-writable-roots.md) | Accepted | 2026-11-13 | | [0034: Gate package networking behind enforceable destination control](0034-gate-package-networking-behind-enforceable-destination-control.md) | Accepted | 2026-11-13 | +| [0035: Fetch packages through a trusted allowlisted cache](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) | Accepted | 2026-11-13 | diff --git a/docs/development-tools.md b/docs/development-tools.md index f793cf6..1f412b8 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -129,7 +129,9 @@ allowlist. The [package-network profile](execution.md#package-network-profile-contract-only) is recorded as configuration only (ADR-0034): `workspace package-profile-add/show/remove` store registry origins, but no run accepts a -profile, and a proxy or proxy environment variables are not a boundary. +profile, and a proxy or proxy environment variables are not a boundary. The +trusted `packages fetch` command contacts only declared origins and writes a +private cache; the run remains offline and does not yet read that cache. Registry credentials require a narrow reviewed credential path. Offline tasks must work with available dependencies or explain which download is needed. @@ -158,12 +160,13 @@ cancellation, denied host-data access, and disabled networking. Include missing dependencies, spaces and native path forms, stale tool profiles, concurrent builds, disk exhaustion, and hostile build/package scripts. -The package-network acceptance case cannot run yet. Profiles are recorded as -configuration only (ADR-0034), and no runtime mechanism narrows destinations. -A future implementation must prove that an approved profile reaches its -declared registry destinations and rejects every other destination, including -direct IP, IPv6, UDP, DNS, and proxy-bypass paths. Model-provider connectivity -alone must not enable package or general task traffic. +The trusted `packages fetch` command is covered by core and CLI tests. The +run-side package-network acceptance case still cannot run: no run accepts a +profile, and no run reads the fetch cache. A future implementation must prove +that an approved profile reaches its declared registry destinations and +rejects every other destination, including direct IP, IPv6, UDP, DNS, and +proxy-bypass paths. Model-provider connectivity alone must not enable package +or general task traffic. Record the selected profile with task results so failures are reproducible. Do not claim general support from locating an executable or printing its version. @@ -184,9 +187,9 @@ yet: - disk exhaustion under concurrent writers, and inode, directory-entry, or metadata exhaustion; the sampled disk limit is tested with ordinary file growth; -- package downloads through `--network`, and rejection of undeclared - destinations, because there is no destination allowlist and the - package-network profile is contract only (ADR-0034); +- package downloads through a run's `--network`, and rejection of undeclared + destinations, because there is no destination allowlist; the trusted + `packages fetch` path is separate and the run does not read its cache; - hostile package scripts beyond the hostile programs. The Java case has not run on either host. The registry case also remains open. diff --git a/docs/execution.md b/docs/execution.md index e4c9752..1111db6 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -47,8 +47,9 @@ per-run disk quota exists, so the supervisor measures growth on a separate thread rather than the kernel enforcing a quota. The [package-network profile](#package-network-profile-contract-only) is -recorded as configuration only (ADR-0034) since version 0.20.0. No run accepts -one, and `--network` remains all-or-nothing. +recorded as configuration only (ADR-0034) since version 0.20.0. Version 0.21.0 +adds a trusted `packages fetch` for declared origins; no run accepts a profile, +`--network` remains all-or-nothing, and the run does not yet read the cache. ## Accepted decisions @@ -251,6 +252,49 @@ Candidate mechanisms for a later decision are a trusted host-side fetch into a private cache with an offline run, an OS destination filter, or a Linux-only network-namespace relay. +### Trusted package fetch + +Version 0.21.0 adds a trusted operator fetch for declared origins; see +[ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md). +It is never a model tool, and the confined run still has no network access. + +```text +omgcode packages fetch --profile --url + --name [--max-bytes <1-1073741824>] + [--timeout-secs <1-600>] +``` + +Before the request it checks: + +1. The workspace is registered and its live `task_network` preference is + enabled. +2. The named package-network profile exists. +3. The URL is absolute and matches a declared origin's scheme, host, port, and + path prefix. It has no credentials, query, or fragment. Normal use is + `https`; `http` is accepted only for a loopback test fixture. +4. The cache name is one safe file name and the file does not already exist. +5. The byte limit is 1 byte to 1 GiB and the deadline is 1 to 600 seconds. + +The request is one GET. Redirects are not followed, proxy environment +variables are ignored, no credentials are sent, and nothing is retried. TLS +uses the operating-system trust store through `reqwest`'s `native-tls` +feature; certificate validation is never disabled. The response must be 2xx +and its body is streamed, hashed with SHA-256, and stopped if it passes the +byte limit. + +The file is written as a private `.partial-` entry, synced, and +renamed to `/package-cache//`. Existing +names are never overwritten. The cache makes no power-loss claim. The control +journal records `package_fetch_started` before the request and +`package_fetch_finished` after it; both preserve the settings revision. They +record the profile identity and revision, a SHA-256 of the URL (never its +text), the cache name, limits, HTTP status, byte count, and content digest. A +failure records a controlled reason. An abandoned fetch leaves its start +record without a finish; nothing retries automatically. + +The run does not yet read this cache. Exposing it read-only to a run is a +separate increment. Registry credentials remain unsupported. + ## Container grants A grant gives one workspace's container access to one directory and everything @@ -865,11 +909,17 @@ These remain true after C6: `listen` on an unbound socket, which takes a port the kernel chooses. UDP bind is never limited. See [network access](#network-access). -- **No package-network enforcement.** Package-network profiles are recorded as - configuration only (ADR-0034). No run accepts one, and it does not narrow - `--network`. A proxy or proxy environment variables are not a boundary: a - hostile tree can connect directly. See - [package-network profile](#package-network-profile-contract-only). +- **No run destination enforcement.** Package-network profiles are recorded, + and the trusted [`packages fetch`](#trusted-package-fetch) command contacts + only declared origins. No run accepts a profile, `--network` remains + all-or-nothing, and the run does not yet read the package cache. A proxy or + proxy environment variables are not a boundary: a hostile tree can connect + directly. +- **Package fetch limits.** The fetch is trusted-CLI only. It sends no + credentials, follows no redirects, ignores proxy variables, and uses the + system TLS store. The cache is private application storage, is not exposed + to runs, and makes no power-loss claim. Tests use loopback HTTP; a live + HTTPS registry is not qualified. - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -922,11 +972,12 @@ These remain true after C6: | C7 (0.19.0) | Sampled disk-growth limit for every trusted run | Done: see [disk growth](#disk-growth) and ADR-0033 | | C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No destination enforcement. | | C9 (0.20.0) | Package-network profile records | Done as configuration: `workspace package-profile-add/show/remove` and the control journal events. No run accepts a profile. | +| C10 (0.21.0) | Trusted allowlisted package fetch | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0035. The run remains offline and does not yet read the cache. | Later work needs its own decisions: -- an enforceable package-network destination mechanism, registry credentials, - and development-server networking; +- exposing the package cache to runs read-only, registry credentials, and + development-server networking; - a model-callable command tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/platform-support.md b/docs/platform-support.md index 88c9a7e..e6f888c 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -22,7 +22,7 @@ containment. | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | -| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform (ADR-0034) ([contract](execution.md#package-network-profile-contract-only)) | +| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a private cache; the run does not read it (ADR-0034, ADR-0035) ([fetch](execution.md#trusted-package-fetch)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index ee7a1c1..62f58e2 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -230,6 +230,12 @@ crate. connect directly. A package-network profile is configuration only until a mechanism constrains every egress path, including direct IP, IPv6, UDP, DNS, loopback, and alternate socket families. See ADR-0034. +- A trusted `packages fetch` is an operator action, never a model tool. It may + contact only a declared origin and path prefix, must disable redirects and + proxy variables, send no credentials, cap and hash the response, and write + only the private per-workspace cache. Record the intent and outcome without + the URL text. Do not expose the private cache to a run without a reviewed + read-only confinement and platform access check. - Assemble and validate a complete structured tool call before dispatch. Validate names, arguments, limits, session scope, and provider call identity. A provider adapter must parse provider JSON strictly; the core runtime then diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 23657ca..af8fcbe 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -143,7 +143,7 @@ As the relevant components are implemented, include: | Processes | Descendant escape attempts, limits, cleanup, startup failure | | Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | -| Package network | Profile storage is implemented: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, and removal. No run accepts a profile and no destination filter exists. A future mechanism must cover allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md)) | +| Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. No run accepts a profile or reads the cache. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | diff --git a/docs/workspace-permissions.md b/docs/workspace-permissions.md index 1e343f0..638855a 100644 --- a/docs/workspace-permissions.md +++ b/docs/workspace-permissions.md @@ -118,6 +118,8 @@ zero-based sequence, UTC timestamp, global revision, and tagged `action`: | `profile_removed` | Remove a toolchain profile; increment revision | | `package_profile_added` | New package-network profile; increment revision | | `package_profile_removed` | Remove a package-network profile; increment revision | +| `package_fetch_started` | Trusted package-fetch intent; preserve revision | +| `package_fetch_finished` | Trusted package-fetch outcome; preserve revision | Operational file checks do not append `policy_checked`. They use current settings and their separate [operation journal](file-access.md). This prevents @@ -186,6 +188,13 @@ one; a 0.20.0 control journal cannot be read by 0.19.0. The [execution guide](execution.md#package-network-profile-contract-only) owns the contract and the remaining enforcement gate. +A trusted `packages fetch` appends `package_fetch_started` and +`package_fetch_finished` events. They preserve the settings revision. They +record the profile identity and revision, a SHA-256 of the request URL (never +the URL text), the cache name, limits, HTTP status, byte count, and content +digest. A failed fetch records a controlled reason; an abandoned fetch leaves +its start event. A control journal written by 0.21.0 cannot be read by 0.20.0. + ## Task network `workspace permissions --revision --task-network true` lets a From e610e61dbdda279cce7f8ca1b8e94f7452b52395 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 00:10:25 +0000 Subject: [PATCH 05/17] feat: expose the package cache to Linux runs read-only When a workspace's fetched-package cache exists as a plain directory, add only that directory to the run's Landlock read-only rules and set OMGCODE_PACKAGE_CACHE. The parent, journals, settings, and other workspaces stay denied, and the run cannot write the cache. Record package_cache in run_started when true. Windows does not expose the cache: the AppContainer cannot read application storage without an ACL grant, and container grants refuse that storage. Version 0.22.0. See ADR-0036. Co-Authored-By: Claude Code --- AGENTS.md | 3 +- CHANGELOG.md | 15 ++++ Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 21 +++-- README.md | 7 +- crates/omgcode-cli/tests/run_workflow.rs | 46 ++++++++++ crates/omgcode-core/src/control/profile.rs | 3 +- crates/omgcode-core/src/run.rs | 39 +++++++-- crates/omgcode-core/src/run_journal.rs | 8 ++ crates/omgcode-core/src/run_journal/tests.rs | 31 +++++++ docs/README.md | 4 +- ...age-fetch-cache-read-only-to-linux-runs.md | 87 +++++++++++++++++++ docs/adr/index.md | 1 + docs/development-tools.md | 6 +- docs/execution.md | 56 +++++++----- docs/platform-support.md | 2 +- docs/security-coding-rules.md | 5 +- docs/testing-standards.md | 2 +- 19 files changed, 296 insertions(+), 48 deletions(-) create mode 100644 docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md diff --git a/AGENTS.md b/AGENTS.md index de91520..070f763 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,8 @@ CPU-time, and sampled net disk-growth limits; on Linux the CLI must run in a delegated cgroup v2. The disk limit measures writable roots and is not a filesystem quota. Package-network profiles are recorded as configuration only; no run uses them. The trusted `packages fetch` command downloads from declared -origins into a private cache, and the run does not yet read it. Trusted CLI +origins into a private cache. Linux runs can read only their workspace's cache; +Windows does not expose it. Trusted CLI commands record, apply, and revoke Windows container ACL grants. Follow the [execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. diff --git a/CHANGELOG.md b/CHANGELOG.md index 836226f..48fe8d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,21 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.22.0 exposes the fetched-package cache to Linux runs read-only. + See ADR-0036. + - **Linux:** when `/package-cache/` exists as a + plain directory, the run gets it read-only and `OMGCODE_PACKAGE_CACHE`. + The parent, journals, settings, and other workspaces stay denied; the run + cannot write the cache. + - **Windows:** the cache is not exposed. The AppContainer cannot read + application storage without an ACL grant, and container grants refuse + that storage. + - **Records:** `run_started` records `package_cache` only when true. A 0.22 + journal that records it cannot be read by 0.21.0. + - **Reserved:** `OMGCODE_PACKAGE_CACHE` cannot be declared in a toolchain + profile. + - **Limits:** no invalidation, eviction, or freshness check; configuring a + toolchain to use the directory is operator work. - Version 0.21.0 adds the trusted operator command `omgcode packages fetch` and a private allowlisted package cache. See ADR-0035. - **Command:** `packages fetch --profile --url diff --git a/Cargo.lock b/Cargo.lock index 3188511..5b3d7e3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -672,7 +672,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.21.0" +version = "0.22.0" dependencies = [ "clap", "directories", @@ -685,7 +685,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.21.0" +version = "0.22.0" dependencies = [ "libc", "omgcode-platform", @@ -701,7 +701,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.21.0" +version = "0.22.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 485760a..64c79fd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.21.0" +version = "0.22.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index f6cd910..9acfe7f 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -61,10 +61,12 @@ This is a resume guide, not a replacement for the owning contracts in - This branch, `codex/package-network-profile`: **Phase C8** at `16d8945`, the contract-only package-network profile and implementation gate (ADR-0034), **Phase C9**, version **0.20.0**, with operator-declared - package-network profile records, and **Phase C10**, version **0.21.0**, with - the trusted allowlisted package fetch and private cache (ADR-0035). It is - stacked on C7 at `0426e42`. No run accepts a profile or reads the cache, and - no run destination filter exists. + package-network profile records, **Phase C10**, version **0.21.0**, with + the trusted allowlisted package fetch and private cache (ADR-0035), and + **Phase C11**, version **0.22.0**, with read-only Linux run access to that + cache (ADR-0036). It is stacked on C7 at `0426e42`. No run accepts a + profile or has destination-scoped networking; Windows does not expose the + cache. Implemented today: @@ -141,6 +143,10 @@ Implemented today: credentials, bounds and hashes the response, writes a private per-workspace cache, and records the intent and outcome. The run remains offline and does not yet read the cache. +- Read-only Linux run access to the workspace's fetched-package cache + (ADR-0036). The cache directory is added to the Landlock read-only rules and + named by `OMGCODE_PACKAGE_CACHE`; its parent and other application storage + stay denied. Windows does not expose it. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -506,10 +512,15 @@ on Windows, and trusted CLI commands as the first caller. See bounds and hashes the body, and audits the intent and outcome. The run remains offline and does not read the cache. See [ADR-0035](docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md). +- **C11 (this branch, version 0.22.0):** read-only Linux run access to the + workspace package cache. The cache directory is a narrow exception to + keeping application storage outside the task view; the parent and sibling + workspaces stay denied. Windows does not expose the cache. See + [ADR-0036](docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md). Next decisions, not yet scheduled: -- exposing the package cache to runs read-only, registry credentials, and +- a Windows package-cache root and grant design, registry credentials, and development-server networking; - a model-callable command tool with per-call approval. diff --git a/README.md b/README.md index 02f5bc5..aa2a022 100644 --- a/README.md +++ b/README.md @@ -39,9 +39,10 @@ directory grants. > recorded as configuration only (ADR-0034); no run uses them and they do not > narrow network access. The trusted `packages fetch` command downloads from > declared origins into a private cache; the run remains offline and does not -> yet read that cache. Runs have memory, process-count, CPU-time, and sampled -> disk-growth limits; the disk limit is not a filesystem quota. See -> [command execution](docs/execution.md#tree-limits). +> yet read that cache on Windows. On Linux a run can read only its workspace's +> cache through `OMGCODE_PACKAGE_CACHE`. Runs have memory, process-count, +> CPU-time, and sampled disk-growth limits; the disk limit is not a filesystem +> quota. See [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index 8441daa..5223fa8 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -28,6 +28,52 @@ fn assert_no_runs(scene: &Scene) { assert_eq!(audit["pending"], Value::Array(Vec::new())); } +/// A Linux run can read only its workspace's package cache. The cache is +/// read-only and its parent application directory stays invisible. +#[cfg(target_os = "linux")] +#[test] +fn a_linux_run_reads_only_its_package_cache() { + let scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + let cache = scene.data.join("package-cache").join(&scene.id); + fs::create_dir_all(&cache).expect("cache directory"); + fs::write(cache.join("pkg.bin"), b"cached-package").expect("cache file"); + let script = "printf '%s\\n' \"$OMGCODE_PACKAGE_CACHE\"; \ + cat \"$OMGCODE_PACKAGE_CACHE/pkg.bin\" > seen.txt; \ + echo x > \"$OMGCODE_PACKAGE_CACHE/out\" 2>/dev/null && echo writable || echo read-only; \ + ls \"$OMGCODE_PACKAGE_CACHE/..\" >/dev/null 2>&1 && echo parent-listed || echo parent-denied"; + let run = run_json(&scene.run("system", &[], &shell(script))); + let stdout = run["stdout"]["text"].as_str().expect("stdout"); + assert!( + stdout.contains(&cache.display().to_string()), + "the cache path was not exposed: {run}" + ); + assert!(stdout.contains("read-only"), "{run}"); + assert!(stdout.contains("parent-denied"), "{run}"); + assert_eq!( + fs::read_to_string(scene.workspace.join("seen.txt")).expect("read cache"), + "cached-package" + ); + assert_eq!(run["start"]["package_cache"], true); + scene.close(); +} + +/// Windows does not expose the application-storage cache to the AppContainer. +#[cfg(windows)] +#[test] +fn windows_runs_do_not_see_the_package_cache() { + let scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + let cache = scene.data.join("package-cache").join(&scene.id); + fs::create_dir_all(&cache).expect("cache directory"); + fs::write(cache.join("pkg.bin"), b"cached-package").expect("cache file"); + let run = run_json(&scene.run("system", &[], &shell("set"))); + let stdout = run["stdout"]["text"].as_str().expect("stdout"); + assert!(!stdout.contains("OMGCODE_PACKAGE_CACHE"), "{run}"); + assert!(run["start"].get("package_cache").is_none(), "{run}"); + scene.close(); +} + /// A run writes in the workspace, cannot read host data, sees only the /// curated environment, and records its intent and outcome but not its /// argument text or output. diff --git a/crates/omgcode-core/src/control/profile.rs b/crates/omgcode-core/src/control/profile.rs index 5ffc78f..9c1c131 100644 --- a/crates/omgcode-core/src/control/profile.rs +++ b/crates/omgcode-core/src/control/profile.rs @@ -31,7 +31,7 @@ pub const MAX_VARIABLE_VALUE_BYTES: usize = 4096; pub const MAX_PROFILE_NAME_CHARS: usize = 64; /// Variables that `run` sets itself. A profile may not set them, in any case. -pub const RESERVED_VARIABLES: [&str; 10] = [ +pub const RESERVED_VARIABLES: [&str; 11] = [ "PATH", "HOME", "TMPDIR", @@ -42,6 +42,7 @@ pub const RESERVED_VARIABLES: [&str; 10] = [ "SYSTEMROOT", "WINDIR", "XDG_CACHE_HOME", + "OMGCODE_PACKAGE_CACHE", ]; /// The native platform a profile was declared on. A profile runs only there. diff --git a/crates/omgcode-core/src/run.rs b/crates/omgcode-core/src/run.rs index 01d8bd7..70d8910 100644 --- a/crates/omgcode-core/src/run.rs +++ b/crates/omgcode-core/src/run.rs @@ -848,7 +848,7 @@ fn prepare( let search_path = std::env::join_paths(&path_entries) .map_err(|_| RunError::Refused("a PATH entry contains the platform's list separator"))?; let mut environment = vec![(OsString::from("PATH"), search_path)]; - let (confinement, scratch, support_paths) = platform_setup( + let (confinement, scratch, support_paths, package_cache) = platform_setup( control, request, &scope.workspace, @@ -893,6 +893,7 @@ fn prepare( } else { None }, + package_cache, }; Ok(Prepared { start, @@ -1032,7 +1033,7 @@ fn platform_setup( data_root: &Path, run_id: Uuid, environment: &mut Vec<(OsString, OsString)>, -) -> Result<(Confinement, Option, Vec), RunError> { +) -> Result<(Confinement, Option, Vec, bool), RunError> { let parent = data_root.join("run-scratch"); crate::storage::create_private_directories(&parent) .map_err(|error| io::Error::other(error.to_string()))?; @@ -1061,6 +1062,13 @@ fn platform_setup( Vec::new() }; read_only.extend(support_paths.iter().cloned()); + // Expose only this workspace's fetched-package cache. Application storage + // otherwise stays outside the run's view. + let package_cache = package_cache_path(data_root, request.workspace_id); + if let Some(cache) = &package_cache { + read_only.push(cache.clone()); + environment.push(("OMGCODE_PACKAGE_CACHE".into(), cache.as_os_str().to_owned())); + } let confinement = Confinement { read_only, read_write: vec![workspace.to_path_buf(), path, PathBuf::from("/dev/null")], @@ -1072,7 +1080,25 @@ fn platform_setup( network: network_access(request), container: None, }; - Ok((confinement, Some(scratch), support_paths)) + Ok(( + confinement, + Some(scratch), + support_paths, + package_cache.is_some(), + )) +} + +/// The private package cache for one workspace, when it exists as a plain +/// directory. A link or other entry is not exposed. +#[cfg(target_os = "linux")] +fn package_cache_path(data_root: &Path, workspace_id: WorkspaceId) -> Option { + let path = data_root + .join("package-cache") + .join(workspace_id.to_string()); + match fs::symlink_metadata(&path) { + Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => Some(path), + _ => None, + } } /// Build the platform confinement and the runner-owned variables. Windows @@ -1094,7 +1120,7 @@ fn platform_setup( _data_root: &Path, _run_id: Uuid, environment: &mut Vec<(OsString, OsString)>, -) -> Result<(Confinement, Option, Vec), RunError> { +) -> Result<(Confinement, Option, Vec, bool), RunError> { use crate::control::container_name; workspace_access(control, request.workspace_id, workspace_record, false) @@ -1119,7 +1145,7 @@ fn platform_setup( network: network_access(request), container: Some(name), }; - Ok((confinement, None, Vec::new())) + Ok((confinement, None, Vec::new(), false)) } #[cfg(not(any(target_os = "linux", windows)))] @@ -1133,7 +1159,7 @@ fn platform_setup( _data_root: &Path, _run_id: Uuid, _environment: &mut Vec<(OsString, OsString)>, -) -> Result<(Confinement, Option, Vec), RunError> { +) -> Result<(Confinement, Option, Vec, bool), RunError> { Err(RunError::Refused( "trusted runs exist only on Linux and Windows", )) @@ -1304,6 +1330,7 @@ mod tests { unix_sockets: SocketMode::PairsOnly, limits: None, network: None, + package_cache: false, } } diff --git a/crates/omgcode-core/src/run_journal.rs b/crates/omgcode-core/src/run_journal.rs index fc7880c..fa2d501 100644 --- a/crates/omgcode-core/src/run_journal.rs +++ b/crates/omgcode-core/src/run_journal.rs @@ -180,6 +180,14 @@ pub struct RunStart { /// runs never had it. #[serde(default, skip_serializing_if = "Option::is_none")] pub network: Option, + /// Whether the run could read the workspace's fetched-package cache, + /// since 0.22.0. False and earlier runs omit it. + #[serde(default, skip_serializing_if = "is_false")] + pub package_cache: bool, +} + +fn is_false(value: &bool) -> bool { + !*value } /// The outcome recorded after a run. diff --git a/crates/omgcode-core/src/run_journal/tests.rs b/crates/omgcode-core/src/run_journal/tests.rs index e3242a8..db94755 100644 --- a/crates/omgcode-core/src/run_journal/tests.rs +++ b/crates/omgcode-core/src/run_journal/tests.rs @@ -25,6 +25,7 @@ fn start(run_id: Uuid) -> RunStart { max_disk_bytes: Some(8 << 30), }), network: None, + package_cache: false, } } @@ -603,3 +604,33 @@ fn pending_starts_and_outcomes_follow_the_recorded_events() { ); assert_eq!(journal.outcome(abandoned), None); } + +/// A package-cache exposure is recorded only when it applies; a run without +/// it keeps the earlier journal shape. +#[test] +fn package_cache_access_is_recorded_only_when_present() { + let directory = tempfile::tempdir().expect("temporary directory"); + let store = store_id(); + let (cached, plain) = (Uuid::new_v4(), Uuid::new_v4()); + let mut cached_start = start(cached); + cached_start.package_cache = true; + let mut journal = RunJournal::open(directory.path(), store).expect("journal"); + journal.start(cached_start).expect("cached start"); + journal.start(start(plain)).expect("plain start"); + drop(journal); + let text = fs::read_to_string(directory.path().join(FILE_NAME)).expect("journal text"); + assert_eq!(text.matches("\"package_cache\"").count(), 1, "{text}"); + assert!(text.contains("\"package_cache\":true"), "{text}"); + let journal = RunJournal::open(directory.path(), store).expect("replay"); + let starts = journal.pending_starts(); + assert!( + starts + .iter() + .any(|start| start.run_id == cached && start.package_cache) + ); + assert!( + starts + .iter() + .any(|start| start.run_id == plain && !start.package_cache) + ); +} diff --git a/docs/README.md b/docs/README.md index f6041ef..971fa34 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,8 +89,8 @@ sampled net disk-growth limits; the disk limit is not a filesystem quota. Package-network profiles are recorded as configuration only (ADR-0034); no run uses them, and network access remains all-or-nothing. The trusted `packages fetch` command downloads from declared origins into a private cache; -the run does not yet read that cache. The -limited file broker and the core read/list turn runtime +Linux runs can read only their workspace's cache, and Windows does not expose +it. The limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed content without writing to the workspace or creating a checkpoint. diff --git a/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md b/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md new file mode 100644 index 0000000..0ac0ada --- /dev/null +++ b/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md @@ -0,0 +1,87 @@ +# 0036: Expose the package fetch cache read-only to Linux runs + +- Status: Accepted +- Date: 2026-11-14 + +## Context + +[ADR-0035](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) adds a +trusted fetch into `/package-cache/`. The confined run +does not read that cache yet, so a fetched package cannot be used by a build +without operator copying. + +The cache is application storage. The project keeps settings and journals +outside the task's view. Exposing the whole data root is unacceptable; only the +per-workspace cache subtree is a candidate. + +On Linux, Landlock can add a read-only path rule for that subtree, and the run +can receive a runner-owned variable naming it. On Windows, the AppContainer +needs an ACL grant to read application storage, and `workspace container-grant` +refuses paths that overlap application storage. A cross-platform cache root +would need a new operator setting and a read-execute container grant; that is +a larger design. + +## Decision + +On Linux, a trusted run exposes the workspace's fetched-package cache when it +exists: + +1. The path is `/package-cache/`. It must exist as a + plain directory; a link or any other entry is not exposed. +2. Only that directory is added to the Landlock read-only rules. The parent + `package-cache` directory, the rest of the data root, and every other + workspace's cache remain outside the run's view. +3. The runner sets `OMGCODE_PACKAGE_CACHE` to the cache path. The variable is + reserved against toolchain profiles, like `HOME` and `PATH`. +4. The run cannot write the cache. The rule is read-only, and the cache files + remain private to the user. +5. `run_started` records `package_cache: true` when the run had this access. + Runs without the cache, and journals written before 0.22.0, omit the field. + A 0.22.0 journal that contains the field cannot be read by 0.21.0. +6. Tool-specific use is operator configuration. The package cache is a + directory and a variable, not an automatic Cargo, npm, or pip cache + integration. + +On Windows, this increment does **not** expose the cache because no +unprivileged AppContainer path can read application storage without weakening +the grant rule. A Windows run keeps working without `OMGCODE_PACKAGE_CACHE`. +A later decision may add an operator-configured cache root with a read-execute +container grant. + +## Alternatives considered + +- **Expose the whole data root read-only.** Rejected: it would expose + settings, journals, and other workspaces' caches. +- **Grant the AppContainer read access to application storage.** Rejected: + it breaks the application-storage overlap rule and exposes more than the + cache. +- **Write the cache into the workspace.** Rejected: the trusted fetch would + bypass the replacement contract, and the run could rewrite the cache. +- **Configure a separate cache root outside application storage and grant it + read-execute to the container.** Deferred: this is the cross-platform fix, + but it needs a new setting, grant rules, and platform qualification. +- **Do not expose the cache on Linux until Windows is ready.** Rejected: the + Linux control is enforceable now, and the gap is explicit. + +## Consequences + +- Linux runs can read fetched packages directly; Windows runs cannot yet. +- The run learns the cache path, and therefore the data-root prefix, through + the variable. It still cannot list or read the parent or any sibling. +- The cache is read-only. There is no invalidation, eviction, cleanup, or + freshness check; the operator manages it. +- The cache is private application storage, and this narrow subtree is a + reviewed exception to keeping application storage outside the task view. + Do not extend the exception to the parent, journals, settings, or other + workspaces. +- Tests cover Linux read access, write denial, parent denial, the journal + field, the reserved variable, and the Windows absence. + +## References + +- [Command execution](../execution.md#trusted-package-fetch) +- [Development tools](../development-tools.md) +- [Workspace settings](../workspace-permissions.md) +- [Security coding rules](../security-coding-rules.md#process-and-sandbox-boundary) +- [Testing standards](../testing-standards.md) +- [ADR-0035](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 270a824..b52e6e5 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -50,3 +50,4 @@ meaningful alternative does not need an ADR. | [0033: Bound run disk growth by sampling writable roots](0033-bound-run-disk-growth-by-sampling-writable-roots.md) | Accepted | 2026-11-13 | | [0034: Gate package networking behind enforceable destination control](0034-gate-package-networking-behind-enforceable-destination-control.md) | Accepted | 2026-11-13 | | [0035: Fetch packages through a trusted allowlisted cache](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) | Accepted | 2026-11-13 | +| [0036: Expose the package fetch cache read-only to Linux runs](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) | Accepted | 2026-11-14 | diff --git a/docs/development-tools.md b/docs/development-tools.md index 1f412b8..c30dc0c 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -131,8 +131,10 @@ is recorded as configuration only (ADR-0034): `workspace package-profile-add/show/remove` store registry origins, but no run accepts a profile, and a proxy or proxy environment variables are not a boundary. The trusted `packages fetch` command contacts only declared origins and writes a -private cache; the run remains offline and does not yet read that cache. -Registry credentials require a narrow reviewed credential path. Offline tasks +private cache. On Linux, a run can read only its workspace's cache through +`OMGCODE_PACKAGE_CACHE`; on Windows the cache is not exposed. Tool-specific +configuration to use that directory is operator work. Registry credentials +require a narrow reviewed credential path. Offline tasks must work with available dependencies or explain which download is needed. Development servers, debuggers, license servers, hardware access, and other diff --git a/docs/execution.md b/docs/execution.md index 1111db6..f9b251f 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -46,10 +46,11 @@ run bounds the allocated bytes it may add to its writable roots. No portable per-run disk quota exists, so the supervisor measures growth on a separate thread rather than the kernel enforcing a quota. -The [package-network profile](#package-network-profile-contract-only) is -recorded as configuration only (ADR-0034) since version 0.20.0. Version 0.21.0 -adds a trusted `packages fetch` for declared origins; no run accepts a profile, -`--network` remains all-or-nothing, and the run does not yet read the cache. +Version 0.22.0 exposes the fetched-package cache to Linux runs read-only. A +run whose workspace has a cache receives `OMGCODE_PACKAGE_CACHE` and may read +that directory, but not its parent or any other application storage. Windows +runs do not get the cache yet; see +[ADR-0036](adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md). ## Accepted decisions @@ -292,8 +293,15 @@ text), the cache name, limits, HTTP status, byte count, and content digest. A failure records a controlled reason. An abandoned fetch leaves its start record without a finish; nothing retries automatically. -The run does not yet read this cache. Exposing it read-only to a run is a -separate increment. Registry credentials remain unsupported. +The run does not contact the registry itself. On Linux, when +`/package-cache/` exists as a plain directory, the run +adds only that directory to its read-only rules and sets +`OMGCODE_PACKAGE_CACHE` to it. The parent `package-cache` directory and the +rest of the data root stay outside the run's view, and the run cannot write +the cache. Windows does not expose the cache because the AppContainer cannot +read application storage without an ACL grant, and container grants refuse +that storage. Tool-specific use of the directory is operator configuration. +Registry credentials remain unsupported. ## Container grants @@ -457,8 +465,8 @@ entries, the runner-owned variables below, and the profile's variables. | Platform | Runner-owned variables | Read-only | Read-write | | --- | --- | --- | --- | -| Linux | `HOME`, `TMPDIR`, and `XDG_CACHE_HOME`, all set to `/run-scratch/` (mode 0700, removed after the run) | Profile roots, `/dev/zero`, `/dev/random`, `/dev/urandom`, and, with `--network`, the [network support paths](#network-access) | The workspace, the scratch directory, `/dev/null` | -| Windows | `LOCALAPPDATA`, `SystemRoot`, `windir`, and `HOME` and `USERPROFILE` set to the container's `AC` folder. Windows then sets `TEMP` and `TMP` inside it | Profile roots, checked against their live ACLs | The workspace, through its grant | +| Linux | `HOME`, `TMPDIR`, and `XDG_CACHE_HOME`, all set to `/run-scratch/` (mode 0700, removed after the run), and, when the workspace cache exists, `OMGCODE_PACKAGE_CACHE` set to `/package-cache/` | Profile roots, `/dev/zero`, `/dev/random`, `/dev/urandom`, the workspace's [package cache](#trusted-package-fetch) when it exists, and, with `--network`, the [network support paths](#network-access) | The workspace, the scratch directory, `/dev/null` | +| Windows | `LOCALAPPDATA`, `SystemRoot`, `windir`, and `HOME` and `USERPROFILE` set to the container's `AC` folder. Windows then sets `TEMP` and `TMP` inside it. The package cache is not exposed | Profile roots, checked against their live ACLs | The workspace, through its grant | Linux runs use `PairsOnly` sockets unless host services were selected. Runs have no IP networking unless `--network` was passed. Windows @@ -641,8 +649,8 @@ Rules: - A name starts with a letter or `_`, continues with letters, digits, or `_`, and is unique case-insensitively. - `PATH`, `HOME`, `TMPDIR`, `TEMP`, `TMP`, `USERPROFILE`, `LOCALAPPDATA`, - `SYSTEMROOT`, `WINDIR`, and `XDG_CACHE_HOME` are reserved for the runner, - in any case. + `SYSTEMROOT`, `WINDIR`, `XDG_CACHE_HOME`, and `OMGCODE_PACKAGE_CACHE` are + reserved for the runner, in any case. - Values are stored in the private settings journal and shown by `status`. Never put secrets in them. - **Limit:** at most 32 profiles. @@ -662,7 +670,7 @@ sequence, a UTC timestamp, and a tagged `action`: | Action | Meaning | | --- | --- | | `created` | Header | -| `run_started` | Synced before the program starts. Records the run ID, workspace, settings revision, profile ID, name, and revision, program path, argument count, `arguments_sha256`, working directory, socket mode, since 0.17.0 `limits` (`max_memory_bytes`, `max_processes`, `max_cpu_ms`, and since 0.19.0 `max_disk_bytes`), and, since 0.18.0 and only for a networked run, `network` with the `support_paths` it could read (at most 32). | +| `run_started` | Synced before the program starts. Records the run ID, workspace, settings revision, profile ID, name, and revision, program path, argument count, `arguments_sha256`, working directory, socket mode, since 0.17.0 `limits` (`max_memory_bytes`, `max_processes`, `max_cpu_ms`, and since 0.19.0 `max_disk_bytes`), since 0.18.0 and only for a networked run `network` with the `support_paths` it could read (at most 32), and, since 0.22.0 and only when true, `package_cache` for read access to the workspace cache. | | `run_finished` | Records the result (`exited`, `signalled`, `deadline_exceeded`, `cancelled`, `revoked`, `limit_exceeded` with its `limit`, `not_started`, `supervision_failed`, or `cleanup_unconfirmed`), the applied confinement, the elapsed time, the output byte counts, and, for a started run, `usage` (`cpu_ms`, where reported `peak_memory_bytes`, and since 0.19.0 `peak_disk_bytes`) | | `run_acknowledged` | The operator cleared a pending run | @@ -681,6 +689,7 @@ How it works: intent is recorded until the outcome is recorded. - **Limits:** at most 16 pending runs; 8 MiB, 4,096 events, and 64 KiB per event. A journal that records the 0.19.0 fields cannot be read by 0.18.0. + A 0.22.0 journal that records `package_cache` cannot be read by 0.21.0. - **Reserve:** a new run must leave room for every pending run's remaining events, 1 KiB each: two for a run in progress, one for a run that needs acknowledgement. @@ -911,15 +920,21 @@ These remain true after C6: [network access](#network-access). - **No run destination enforcement.** Package-network profiles are recorded, and the trusted [`packages fetch`](#trusted-package-fetch) command contacts - only declared origins. No run accepts a profile, `--network` remains - all-or-nothing, and the run does not yet read the package cache. A proxy or - proxy environment variables are not a boundary: a hostile tree can connect - directly. + only declared origins. No run accepts a profile, and `--network` remains + all-or-nothing. On Linux a run can read only its workspace's cache; Windows + does not expose the cache. A proxy or proxy environment variables are not a + boundary: a hostile tree can connect directly. - **Package fetch limits.** The fetch is trusted-CLI only. It sends no credentials, follows no redirects, ignores proxy variables, and uses the - system TLS store. The cache is private application storage, is not exposed - to runs, and makes no power-loss claim. Tests use loopback HTTP; a live - HTTPS registry is not qualified. + system TLS store. The cache is private application storage; only the + per-workspace subtree is exposed to Linux runs, read-only. It makes no + power-loss claim. Tests use loopback HTTP; a live HTTPS registry is not + qualified. +- **Package cache exposure is Linux-only.** A Linux run receives + `OMGCODE_PACKAGE_CACHE` and may read that directory, but not its parent, + journals, settings, or another workspace's cache. Windows does not expose + it. There is no invalidation, eviction, or freshness check, and configuring + a toolchain to use the directory is operator work. - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -972,11 +987,12 @@ These remain true after C6: | C7 (0.19.0) | Sampled disk-growth limit for every trusted run | Done: see [disk growth](#disk-growth) and ADR-0033 | | C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No destination enforcement. | | C9 (0.20.0) | Package-network profile records | Done as configuration: `workspace package-profile-add/show/remove` and the control journal events. No run accepts a profile. | -| C10 (0.21.0) | Trusted allowlisted package fetch | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0035. The run remains offline and does not yet read the cache. | +| C10 (0.21.0) | Trusted allowlisted package fetch | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0035. The run remains offline. | +| C11 (0.22.0) | Read-only package cache for Linux runs | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0036. Windows does not expose the cache. | Later work needs its own decisions: -- exposing the package cache to runs read-only, registry credentials, and +- a Windows package-cache root and grant design, registry credentials, and development-server networking; - a model-callable command tool. diff --git a/docs/platform-support.md b/docs/platform-support.md index e6f888c..3830e37 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -22,7 +22,7 @@ containment. | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | -| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a private cache; the run does not read it (ADR-0034, ADR-0035) ([fetch](execution.md#trusted-package-fetch)) | +| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a private cache. Linux runs read only their workspace's cache; Windows does not expose it (ADR-0034, ADR-0035, ADR-0036) ([fetch](execution.md#trusted-package-fetch)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 62f58e2..360390b 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -234,8 +234,9 @@ crate. contact only a declared origin and path prefix, must disable redirects and proxy variables, send no credentials, cap and hash the response, and write only the private per-workspace cache. Record the intent and outcome without - the URL text. Do not expose the private cache to a run without a reviewed - read-only confinement and platform access check. + the URL text. A Linux run may read only the per-workspace cache subtree; do + not expose its parent, journals, settings, or another workspace. Do not + expose the cache on a platform that cannot enforce the same boundary. - Assemble and validate a complete structured tool call before dispatch. Validate names, arguments, limits, session scope, and provider call identity. A provider adapter must parse provider JSON strictly; the core runtime then diff --git a/docs/testing-standards.md b/docs/testing-standards.md index af8fcbe..3f8aca1 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -143,7 +143,7 @@ As the relevant components are implemented, include: | Processes | Descendant escape attempts, limits, cleanup, startup failure | | Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | -| Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. No run accepts a profile or reads the cache. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md)) | +| Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. Linux cache exposure covers read access, write denial, parent denial, the reserved variable, and the `package_cache` journal field; Windows covers the variable's absence. No run accepts a profile. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md), [ADR-0036](adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | From f4a887e87def559796486b9091d404264ffa3bc7 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 00:11:27 +0000 Subject: [PATCH 06/17] docs: correct the remaining planned execution claims Trusted CLI process and network confinement are implemented; what remains planned is model-dispatched process execution, plus Git, MCP, and memories. Co-Authored-By: Claude Code --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aa2a022..e98dc94 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ an explicit current-content check. Trusted `file delete-checkpoint --permanent` removes one resolved checkpoint's files and keeps its ledger history. Neither command is power-loss qualified. Model-dispatched write tools remain unavailable. -Process/network confinement, Git, MCP, and memories remain planned. See the +Model-dispatched process execution, Git, MCP, and memories remain planned. See the [workspace settings contract](docs/workspace-permissions.md), the [workspace file-access guide](docs/file-access.md), and the [development guide](docs/development.md) for limits and command details. From 22a38c3ec2d9c0f258665ccab9a6e09387ad8765 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 00:29:42 +0000 Subject: [PATCH 07/17] feat: add per-workspace package cache roots Add `workspace set-package-cache` and `clear-package-cache`, recording one cache root per workspace outside application storage and the development root. Overlapping roots are refused. `packages fetch` writes into the selected root, or the Linux application-storage fallback when none is selected. A selected root is exposed read-only to runs on Linux and Windows and named by OMGCODE_PACKAGE_CACHE. Windows requires a read-execute container grant on that root and traversable ancestors; without the grant the run fails before the program starts. Supersedes ADR-0036 with ADR-0037. Version 0.23.0. Co-Authored-By: Claude Code --- AGENTS.md | 5 +- CHANGELOG.md | 18 +++ Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 30 ++-- README.md | 11 +- crates/omgcode-cli/src/control_cli.rs | 39 +++++ crates/omgcode-cli/tests/run_workflow.rs | 102 ++++++++++++ crates/omgcode-core/src/control.rs | 147 ++++++++++++++++++ crates/omgcode-core/src/packages.rs | 23 ++- crates/omgcode-core/src/packages/tests.rs | 23 +++ crates/omgcode-core/src/run.rs | 53 +++++-- crates/omgcode-core/tests/control_store.rs | 79 ++++++++++ docs/README.md | 7 +- ...age-fetch-cache-read-only-to-linux-runs.md | 3 +- ...e-cache-root-and-a-scoped-windows-grant.md | 94 +++++++++++ docs/adr/index.md | 3 +- docs/development-tools.md | 14 +- docs/execution.md | 77 +++++---- docs/platform-support.md | 2 +- docs/security-coding-rules.md | 8 +- docs/testing-standards.md | 2 +- docs/workspace-permissions.md | 16 ++ 23 files changed, 677 insertions(+), 87 deletions(-) create mode 100644 docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md diff --git a/AGENTS.md b/AGENTS.md index 070f763..b8bd257 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,8 +20,9 @@ CPU-time, and sampled net disk-growth limits; on Linux the CLI must run in a delegated cgroup v2. The disk limit measures writable roots and is not a filesystem quota. Package-network profiles are recorded as configuration only; no run uses them. The trusted `packages fetch` command downloads from declared -origins into a private cache. Linux runs can read only their workspace's cache; -Windows does not expose it. Trusted CLI +origins into a per-workspace cache. A selected root is exposed read-only on +Linux and Windows; Windows needs a read-execute container grant, and Linux +falls back to application storage. Trusted CLI commands record, apply, and revoke Windows container ACL grants. Follow the [execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. diff --git a/CHANGELOG.md b/CHANGELOG.md index 48fe8d3..f91a05e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,24 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.23.0 adds a per-workspace package cache root and scoped Windows + access. See ADR-0037. + - **Commands:** `workspace set-package-cache + --revision ` and `workspace clear-package-cache + --revision `. `status` lists roots under `package_cache_roots`. + - **Rules:** the root must exist, must not overlap application storage or + the development root, and must not overlap another workspace's root. + - **Fetch:** `packages fetch` writes into the selected root. Without one, + Linux keeps the application-storage fallback and Windows has none. + - **Runs:** a selected root is exposed read-only and named by + `OMGCODE_PACKAGE_CACHE` on both platforms. Windows requires a read-execute + container grant on that root and traversable ancestors; without the grant + the run fails before the program starts. `run_started` records + `package_cache` when true. + - **Records:** `package_cache_root_set` and `package_cache_root_cleared` in + the control journal. A 0.23.0 control journal cannot be read by 0.22.0. + - **Limits:** no invalidation, eviction, or freshness check; changing the + root leaves old files and old grants for the operator to manage. - Version 0.22.0 exposes the fetched-package cache to Linux runs read-only. See ADR-0036. - **Linux:** when `/package-cache/` exists as a diff --git a/Cargo.lock b/Cargo.lock index 5b3d7e3..5574255 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -672,7 +672,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.22.0" +version = "0.23.0" dependencies = [ "clap", "directories", @@ -685,7 +685,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.22.0" +version = "0.23.0" dependencies = [ "libc", "omgcode-platform", @@ -701,7 +701,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.22.0" +version = "0.23.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 64c79fd..7996307 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.22.0" +version = "0.23.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 9acfe7f..e4bd809 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -64,9 +64,9 @@ This is a resume guide, not a replacement for the owning contracts in package-network profile records, **Phase C10**, version **0.21.0**, with the trusted allowlisted package fetch and private cache (ADR-0035), and **Phase C11**, version **0.22.0**, with read-only Linux run access to that - cache (ADR-0036). It is stacked on C7 at `0426e42`. No run accepts a - profile or has destination-scoped networking; Windows does not expose the - cache. + cache (ADR-0036), and **Phase C12**, version **0.23.0**, with per-workspace + cache roots and scoped Windows access (ADR-0037). It is stacked on C7 at + `0426e42`. No run accepts a profile or has destination-scoped networking. Implemented today: @@ -143,10 +143,12 @@ Implemented today: credentials, bounds and hashes the response, writes a private per-workspace cache, and records the intent and outcome. The run remains offline and does not yet read the cache. -- Read-only Linux run access to the workspace's fetched-package cache - (ADR-0036). The cache directory is added to the Landlock read-only rules and - named by `OMGCODE_PACKAGE_CACHE`; its parent and other application storage - stay denied. Windows does not expose it. +- Read-only run access to a per-workspace fetched-package cache root + (ADR-0037, superseding ADR-0036). The root is selected with + `workspace set-package-cache`, exposed read-only on Linux and Windows, and + named by `OMGCODE_PACKAGE_CACHE`. Windows requires a read-execute container + grant on the root; Linux falls back to application storage when no root is + selected. Overlapping roots are refused. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -513,15 +515,17 @@ on Windows, and trusted CLI commands as the first caller. See remains offline and does not read the cache. See [ADR-0035](docs/adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md). - **C11 (this branch, version 0.22.0):** read-only Linux run access to the - workspace package cache. The cache directory is a narrow exception to - keeping application storage outside the task view; the parent and sibling - workspaces stay denied. Windows does not expose the cache. See - [ADR-0036](docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md). + workspace package cache. Superseded by C12, which moves exposure to a + per-workspace root and adds Windows access. +- **C12 (this branch, version 0.23.0):** per-workspace cache roots and a + scoped Windows grant. The operator selects a root outside application + storage and the development root; fetch and run use it; Windows needs a + read-execute grant on that root. See + [ADR-0037](docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md). Next decisions, not yet scheduled: -- a Windows package-cache root and grant design, registry credentials, and - development-server networking; +- registry credentials and development-server networking; - a model-callable command tool with per-call approval. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index e98dc94..de9a9b7 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,12 @@ directory grants. > as service and credential-agent sockets. Package-network profiles can be > recorded as configuration only (ADR-0034); no run uses them and they do not > narrow network access. The trusted `packages fetch` command downloads from -> declared origins into a private cache; the run remains offline and does not -> yet read that cache on Windows. On Linux a run can read only its workspace's -> cache through `OMGCODE_PACKAGE_CACHE`. Runs have memory, process-count, -> CPU-time, and sampled disk-growth limits; the disk limit is not a filesystem -> quota. See [command execution](docs/execution.md#tree-limits). +> declared origins into a private per-workspace cache. A selected cache root +> is exposed read-only on Linux and Windows; Windows needs a read-execute +> container grant, and Linux falls back to application storage when no root is +> selected. Runs have memory, process-count, CPU-time, and sampled disk-growth +> limits; the disk limit is not a filesystem quota. See +> [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/crates/omgcode-cli/src/control_cli.rs b/crates/omgcode-cli/src/control_cli.rs index d882eff..8fb760b 100644 --- a/crates/omgcode-cli/src/control_cli.rs +++ b/crates/omgcode-cli/src/control_cli.rs @@ -27,6 +27,20 @@ pub(crate) enum WorkspaceCommand { #[arg(long)] revision: u64, }, + /// Select one workspace's fetched-package cache root, outside application + /// storage and the development root. + SetPackageCache { + workspace: String, + path: PathBuf, + #[arg(long)] + revision: u64, + }, + /// Clear one workspace's package cache root. Cached files are left in place. + ClearPackageCache { + workspace: String, + #[arg(long)] + revision: u64, + }, /// Register a workspace below the configured development root. Register { path: PathBuf, @@ -204,6 +218,31 @@ pub(crate) fn run(action: WorkspaceCommand, data_root: &Path) -> Result<(), CliE stop_withdrawn_runs(data_root, &[])?; print_json(&snapshot) } + WorkspaceCommand::SetPackageCache { + workspace, + path, + revision, + } => { + let workspace_id = parse_workspace_id(&workspace)?; + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + store + .set_package_cache_root(workspace_id, &path, revision) + .map_err(control_error)?; + print_json(&store.snapshot()) + } + WorkspaceCommand::ClearPackageCache { + workspace, + revision, + } => { + let workspace_id = parse_workspace_id(&workspace)?; + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + store + .clear_package_cache_root(workspace_id, revision) + .map_err(control_error)?; + print_json(&store.snapshot()) + } WorkspaceCommand::Register { path, revision } => { let mut store = open(data_root)?; let registration = store diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index 5223fa8..d1aac3b 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -28,6 +28,108 @@ fn assert_no_runs(scene: &Scene) { assert_eq!(audit["pending"], Value::Array(Vec::new())); } +/// A configured cache root is exposed read-only on Linux without using +/// application storage. +#[cfg(target_os = "linux")] +#[test] +fn a_linux_run_reads_a_configured_package_cache_root() { + let scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + let cache_root = scene.path("package-cache-root"); + fs::create_dir(&cache_root).expect("cache root"); + let output = scene.cli(&[ + "workspace", + "set-package-cache", + &scene.id, + path_arg(&cache_root), + "--revision", + &scene.revision().to_string(), + ]); + assert_success(&output); + fs::write(cache_root.join("pkg.bin"), b"configured-cache").expect("cache file"); + let cache = cache_root.clone(); + let script = "printf '%s\\n' \"$OMGCODE_PACKAGE_CACHE\"; \ + cat \"$OMGCODE_PACKAGE_CACHE/pkg.bin\" > seen.txt; \ + echo x > \"$OMGCODE_PACKAGE_CACHE/out\" 2>/dev/null && echo writable || echo read-only; \ + ls \"$OMGCODE_PACKAGE_CACHE/..\" >/dev/null 2>&1 && echo parent-listed || echo parent-denied"; + let run = run_json(&scene.run("system", &[], &shell(script))); + let stdout = run["stdout"]["text"].as_str().expect("stdout"); + assert!( + stdout.contains(&cache.display().to_string()), + "the configured cache path was not exposed: {run}" + ); + assert!(stdout.contains("read-only"), "{run}"); + assert!(stdout.contains("parent-denied"), "{run}"); + assert_eq!( + fs::read_to_string(scene.workspace.join("seen.txt")).expect("read cache"), + "configured-cache" + ); + assert_eq!(run["start"]["package_cache"], true); + scene.close(); +} + +/// On Windows a configured cache root is exposed only after the container +/// receives a read-execute grant on the per-workspace cache directory. +#[cfg(windows)] +#[test] +fn a_windows_run_reads_a_granted_package_cache_root() { + let mut scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + // A top-level root has ancestors app packages can traverse; a root beneath + // the user's private temp directory cannot be reached by the container. + let cache_root = tempfile::TempDir::new_in("C:\\").expect("top-level cache root"); + let cache_root_path = cache_root.path().to_path_buf(); + let output = scene.cli(&[ + "workspace", + "set-package-cache", + &scene.id, + path_arg(&cache_root_path), + "--revision", + &scene.revision().to_string(), + ]); + assert_success(&output); + fs::write(cache_root_path.join("pkg.bin"), b"configured-cache").expect("cache file"); + let cache = cache_root_path.clone(); + scene.grant(&cache_root_path, "read-execute"); + let script = "type %OMGCODE_PACKAGE_CACHE%\\pkg.bin & echo %OMGCODE_PACKAGE_CACHE%"; + let run = run_json(&scene.run("system", &[], &shell(script))); + let stdout = run["stdout"]["text"].as_str().expect("stdout"); + assert!( + stdout.contains(&cache.display().to_string()), + "the configured cache path was not exposed: {run}" + ); + assert!( + stdout.contains("configured-cache"), + "the cache file was not read: {run}" + ); + assert_eq!(run["start"]["package_cache"], true); + scene.close(); +} + +/// Without the container grant, the configured cache path fails the run +/// before the program starts. +#[cfg(windows)] +#[test] +fn an_ungranted_package_cache_root_fails_the_run() { + let scene = Scene::new(); + assert_success(&scene.add_profile("system", &[])); + let cache_root = scene.path("package-cache-root"); + fs::create_dir(&cache_root).expect("cache root"); + let output = scene.cli(&[ + "workspace", + "set-package-cache", + &scene.id, + path_arg(&cache_root), + "--revision", + &scene.revision().to_string(), + ]); + assert_success(&output); + fs::write(cache_root.join("pkg.bin"), b"configured-cache").expect("cache file"); + let output = scene.run("system", &[], &shell("echo should-not-run")); + assert_error_code(&output, "run"); + scene.close(); +} + /// A Linux run can read only its workspace's package cache. The cache is /// read-only and its parent application directory stays invisible. #[cfg(target_os = "linux")] diff --git a/crates/omgcode-core/src/control.rs b/crates/omgcode-core/src/control.rs index 866d149..73ca1d4 100644 --- a/crates/omgcode-core/src/control.rs +++ b/crates/omgcode-core/src/control.rs @@ -116,6 +116,9 @@ pub enum ControlError { /// The requested package-network profile is invalid. #[error("package-network profile refused: {0}")] PackageProfileRefused(&'static str), + /// The requested package cache root is invalid or overlaps protected data. + #[error("package cache root refused: {0}")] + PackageCacheRefused(&'static str), } impl From for ControlError { @@ -173,6 +176,10 @@ pub struct ControlSnapshot { profiles: Vec, #[serde(skip_serializing_if = "Vec::is_empty")] package_profiles: Vec, + /// Operator-selected fetched-package roots, one per workspace, outside + /// application storage and the development root. + #[serde(skip_serializing_if = "Vec::is_empty")] + package_cache_roots: Vec, /// Container revocations requested per workspace since the journal was /// created. Derived on replay and never serialized; run watchers compare /// it with the count when their run started. @@ -180,6 +187,14 @@ pub struct ControlSnapshot { grant_revocations: BTreeMap, } +/// One workspace's selected fetched-package cache root. +#[derive(Clone, Debug, Serialize)] +pub struct PackageCacheRootStatus { + workspace_id: WorkspaceId, + directory: DirectoryRecord, + revision: u64, +} + /// Operator-facing workspace view that reports every preference explicitly. /// /// Persisted records omit a disabled `model_tools` flag for compatibility; @@ -285,6 +300,15 @@ enum Action { PackageFetchFinished { finish: PackageFetchFinish, }, + PackageCacheRootSet { + #[serde(deserialize_with = "deserialize_workspace_id")] + workspace_id: WorkspaceId, + directory: DirectoryRecord, + }, + PackageCacheRootCleared { + #[serde(deserialize_with = "deserialize_workspace_id")] + workspace_id: WorkspaceId, + }, } /// One persisted settings/audit event, never prompts or dedicated credential fields. @@ -451,6 +475,7 @@ impl ControlStore { container_grants: Vec::new(), profiles: Vec::new(), package_profiles: Vec::new(), + package_cache_roots: Vec::new(), grant_revocations: BTreeMap::new(), }, entries: Vec::new(), @@ -473,6 +498,91 @@ impl ControlStore { pub const fn has_development_root(&self) -> bool { self.snapshot.development_root.is_some() } + + /// Select the fetched-package cache directory for one workspace. It must + /// exist, must not overlap application storage, must not overlap the + /// development root, and must not overlap another workspace's cache root. + pub fn set_package_cache_root( + &mut self, + workspace_id: WorkspaceId, + path: &Path, + expected_revision: u64, + ) -> Result<(), ControlError> { + self.check_revision(expected_revision)?; + if self.workspace(workspace_id).is_none() { + return Err(ControlError::UnknownWorkspace); + } + let directory = DirectoryRecord::capture(path)?; + self.check_storage_overlap(&directory)?; + let development = self + .snapshot + .development_root + .as_ref() + .ok_or(ControlError::NoRoot)?; + if development.contains(&directory)? || directory.contains(development)? { + return Err(ControlError::PackageCacheRefused( + "the package cache root must not overlap the development root", + )); + } + for existing in &self.snapshot.package_cache_roots { + if existing.workspace_id != workspace_id + && (existing.directory.contains(&directory)? + || directory.contains(&existing.directory)?) + { + return Err(ControlError::PackageCacheRefused( + "package cache roots must not overlap another workspace's root", + )); + } + } + if self.snapshot.package_cache_roots.iter().any(|existing| { + existing.workspace_id == workspace_id && existing.directory.same_directory(&directory) + }) { + return Ok(()); + } + self.append( + Action::PackageCacheRootSet { + workspace_id, + directory, + }, + self.next_revision()?, + )?; + Ok(()) + } + + /// Clear one workspace's package cache root. This advances the settings + /// revision only when a root was recorded. Cached files are left in place. + pub fn clear_package_cache_root( + &mut self, + workspace_id: WorkspaceId, + expected_revision: u64, + ) -> Result<(), ControlError> { + self.check_revision(expected_revision)?; + if self.workspace(workspace_id).is_none() { + return Err(ControlError::UnknownWorkspace); + } + if !self + .snapshot + .package_cache_roots + .iter() + .any(|existing| existing.workspace_id == workspace_id) + { + return Ok(()); + } + self.append( + Action::PackageCacheRootCleared { workspace_id }, + self.next_revision()?, + )?; + Ok(()) + } + + /// The selected package cache root for one workspace, if any. + pub(crate) fn package_cache_root(&self, workspace_id: WorkspaceId) -> Option<&DirectoryRecord> { + self.snapshot + .package_cache_roots + .iter() + .find(|status| status.workspace_id == workspace_id) + .map(|status| &status.directory) + } /// Look up descriptive workspace metadata by its stable identifier. pub fn workspace(&self, id: WorkspaceId) -> Option<&WorkspaceRegistration> { self.snapshot @@ -949,6 +1059,43 @@ impl ControlStore { | Action::PackageFetchFinished { .. } => { package::apply(state, &entry.action, revision)?; } + Action::PackageCacheRootSet { + workspace_id, + directory, + } => { + if !directory.validate_shape() + || !state + .workspaces + .iter() + .any(|workspace| workspace.id == *workspace_id) + { + return Err(ControlError::Invalid("invalid package cache root")); + } + if let Some(existing) = state + .package_cache_roots + .iter_mut() + .find(|status| status.workspace_id == *workspace_id) + { + existing.directory = directory.clone(); + existing.revision = revision; + } else { + state.package_cache_roots.push(PackageCacheRootStatus { + workspace_id: *workspace_id, + directory: directory.clone(), + revision, + }); + } + } + Action::PackageCacheRootCleared { workspace_id } => { + let index = state + .package_cache_roots + .iter() + .position(|status| status.workspace_id == *workspace_id) + .ok_or(ControlError::Invalid( + "clearing an unknown package cache root", + ))?; + state.package_cache_roots.remove(index); + } } state.revision = revision; Ok(()) diff --git a/crates/omgcode-core/src/packages.rs b/crates/omgcode-core/src/packages.rs index 3a382e1..240ae40 100644 --- a/crates/omgcode-core/src/packages.rs +++ b/crates/omgcode-core/src/packages.rs @@ -14,7 +14,7 @@ use std::fmt::Write as _; use std::fs::{self, OpenOptions}; use std::io::{self, Read, Write}; -use std::path::{Path, PathBuf}; +use std::path::Path; use std::thread; use std::time::{Duration, Instant}; @@ -170,7 +170,20 @@ pub fn fetch(data_root: &Path, request: &FetchRequest) -> Result { + if !root.is_current().unwrap_or(false) { + return Err(FetchError::Refused( + "the package cache root is stale; set it again", + )); + } + root.live_path() + .map_err(|_| FetchError::Refused("the package cache root is unavailable"))? + } + None => data_root + .join("package-cache") + .join(request.workspace_id.to_string()), + }; storage::create_private_directories(&cache) .map_err(|error| FetchError::Cache(io::Error::other(error.to_string())))?; let final_path = cache.join(&request.name); @@ -258,12 +271,6 @@ fn validate_request(request: &FetchRequest) -> Result<(), FetchError> { Ok(()) } -fn cache_directory(data_root: &Path, workspace_id: WorkspaceId) -> PathBuf { - data_root - .join("package-cache") - .join(workspace_id.to_string()) -} - /// Require the URL to match a declared origin and path prefix, with no /// credentials, query, or fragment. fn matching_origin(profile: &PackageProfile, url: &Url) -> Result<(), FetchError> { diff --git a/crates/omgcode-core/src/packages/tests.rs b/crates/omgcode-core/src/packages/tests.rs index f412aca..6c4ab66 100644 --- a/crates/omgcode-core/src/packages/tests.rs +++ b/crates/omgcode-core/src/packages/tests.rs @@ -1,5 +1,6 @@ use super::*; use std::net::{SocketAddr, TcpListener, TcpStream}; +use std::path::PathBuf; use std::thread::{self, JoinHandle}; use std::time::{Duration, Instant}; @@ -197,6 +198,28 @@ fn a_declared_origin_is_fetched_and_audited() { assert!(audit.contains("\"kind\":\"fetched\""), "{audit}"); } +#[test] +fn a_configured_cache_root_receives_the_fetch() { + let body = b"external-cache".to_vec(); + let fixture = Fixture::start(200, body.clone(), ""); + let scene = Scene::new(&[format!("http://{}/fixtures/", fixture.address)]); + let cache_root = scene._directory.path().join("external-cache"); + fs::create_dir(&cache_root).expect("cache root"); + let mut store = ControlStore::open(&scene.data).expect("store"); + store + .set_package_cache_root(scene.workspace_id, &cache_root, store.revision()) + .expect("cache root"); + drop(store); + let url = fixture.url("/fixtures/pkg.bin"); + let report = fetch(&scene.data, &scene.request(url, "pkg.bin", 1024)).expect("fetch"); + assert_eq!(report.bytes, body.len() as u64); + let cached = cache_root.join("pkg.bin"); + assert_eq!(fs::read(cached).expect("external cache file"), body); + assert!(!scene.cache_file("pkg.bin").exists()); + let head = fixture.finish(); + assert!(head.starts_with("GET /fixtures/pkg.bin "), "{head}"); +} + #[test] fn an_undeclared_origin_or_path_is_refused_before_a_request() { // A closed loopback port stands in for an origin that was not declared. diff --git a/crates/omgcode-core/src/run.rs b/crates/omgcode-core/src/run.rs index 70d8910..48ed20f 100644 --- a/crates/omgcode-core/src/run.rs +++ b/crates/omgcode-core/src/run.rs @@ -1025,7 +1025,7 @@ fn network_access(request: &RunRequest) -> NetworkAccess { #[cfg(target_os = "linux")] #[allow(clippy::too_many_arguments)] fn platform_setup( - _control: &ControlStore, + control: &ControlStore, request: &RunRequest, _workspace_record: &DirectoryRecord, workspace: &Path, @@ -1064,7 +1064,7 @@ fn platform_setup( read_only.extend(support_paths.iter().cloned()); // Expose only this workspace's fetched-package cache. Application storage // otherwise stays outside the run's view. - let package_cache = package_cache_path(data_root, request.workspace_id); + let package_cache = package_cache_path(control, data_root, request.workspace_id); if let Some(cache) = &package_cache { read_only.push(cache.clone()); environment.push(("OMGCODE_PACKAGE_CACHE".into(), cache.as_os_str().to_owned())); @@ -1089,12 +1089,37 @@ fn platform_setup( } /// The private package cache for one workspace, when it exists as a plain -/// directory. A link or other entry is not exposed. -#[cfg(target_os = "linux")] -fn package_cache_path(data_root: &Path, workspace_id: WorkspaceId) -> Option { - let path = data_root - .join("package-cache") - .join(workspace_id.to_string()); +/// directory. A configured root outside application storage takes precedence. +/// Linux falls back to its application-storage cache; Windows has no fallback. +/// A link or other entry is not exposed. +fn package_cache_path( + control: &ControlStore, + data_root: &Path, + workspace_id: WorkspaceId, +) -> Option { + let path = match control.package_cache_root(workspace_id) { + Some(root) => { + if !root.is_current().ok()? { + return None; + } + root.live_path().ok()? + } + None => { + #[cfg(target_os = "linux")] + { + data_root + .join("package-cache") + .join(workspace_id.to_string()) + } + #[cfg(not(target_os = "linux"))] + { + let _ = data_root; + return None; + } + } + }; + // Normalize a recorded Windows path to the drive-letter form tools accept. + let path = native_form(path).ok()?; match fs::symlink_metadata(&path) { Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => Some(path), _ => None, @@ -1117,7 +1142,7 @@ fn platform_setup( workspace_record: &DirectoryRecord, workspace: &Path, roots: Vec, - _data_root: &Path, + data_root: &Path, _run_id: Uuid, environment: &mut Vec<(OsString, OsString)>, ) -> Result<(Confinement, Option, Vec, bool), RunError> { @@ -1138,14 +1163,20 @@ fn platform_setup( } environment.push(("HOME".into(), home.clone().into_os_string())); environment.push(("USERPROFILE".into(), home.into_os_string())); + let package_cache = package_cache_path(control, data_root, request.workspace_id); + let mut read_only = roots; + if let Some(cache) = &package_cache { + read_only.push(cache.clone()); + environment.push(("OMGCODE_PACKAGE_CACHE".into(), cache.as_os_str().to_owned())); + } let confinement = Confinement { - read_only: roots, + read_only, read_write: vec![workspace.to_path_buf()], unix_sockets: UnixSocketAccess::PairsOnly, network: network_access(request), container: Some(name), }; - Ok((confinement, None, Vec::new(), false)) + Ok((confinement, None, Vec::new(), package_cache.is_some())) } #[cfg(not(any(target_os = "linux", windows)))] diff --git a/crates/omgcode-core/tests/control_store.rs b/crates/omgcode-core/tests/control_store.rs index d02f273..c9cfdb3 100644 --- a/crates/omgcode-core/tests/control_store.rs +++ b/crates/omgcode-core/tests/control_store.rs @@ -513,3 +513,82 @@ fn malformed_control_journals_fail_without_repair() { expect_invalid_unchanged(&data); } } + +/// One workspace's package cache root is a revisioned setting. It must be +/// existing, outside application storage, outside the development root, and +/// not overlap another workspace's cache root. +#[test] +fn package_cache_root_is_recorded_replayed_cleared_and_scoped() { + let fixture = fixture(); + let cache_root = fixture._temporary.path().join("package-cache-root"); + fs::create_dir(&cache_root).expect("cache root"); + let nested = cache_root.join("nested"); + fs::create_dir(&nested).expect("nested cache root"); + let inside = fixture.root.join("cache-inside"); + fs::create_dir(&inside).expect("inside development root"); + let mut store = ControlStore::open(&fixture.data).expect("store"); + store + .set_development_root(&fixture.root, 0) + .expect("development root"); + let workspace_id = store + .register_workspace(&fixture.workspace, store.revision()) + .expect("workspace") + .id(); + let second_id = store + .register_workspace(&fixture.second_workspace, store.revision()) + .expect("second workspace") + .id(); + let revision = store.revision(); + store + .set_package_cache_root(workspace_id, &cache_root, revision) + .expect("cache root"); + assert!( + serde_json::to_value(store.snapshot()) + .expect("snapshot") + .get("package_cache_roots") + .is_some() + ); + let revision = store.revision(); + assert!(matches!( + store.set_package_cache_root(workspace_id, &inside, revision), + Err(ControlError::PackageCacheRefused(_)) + )); + assert!(matches!( + store.set_package_cache_root(workspace_id, &fixture.data, revision), + Err(ControlError::StorageOverlap) + )); + assert!(matches!( + store.set_package_cache_root(second_id, &nested, revision), + Err(ControlError::PackageCacheRefused(_)) + )); + let missing = fixture._temporary.path().join("missing-cache"); + assert!( + store + .set_package_cache_root(workspace_id, &missing, revision) + .is_err() + ); + drop(store); + + let mut store = ControlStore::open(&fixture.data).expect("replay"); + assert!( + serde_json::to_value(store.snapshot()) + .expect("snapshot") + .get("package_cache_roots") + .is_some() + ); + let revision = store.revision(); + store + .clear_package_cache_root(workspace_id, revision) + .expect("clear cache root"); + assert!( + serde_json::to_value(store.snapshot()) + .expect("snapshot") + .get("package_cache_roots") + .is_none() + ); + let revision = store.revision(); + store + .clear_package_cache_root(workspace_id, revision) + .expect("idempotent clear"); + assert_eq!(store.revision(), revision); +} diff --git a/docs/README.md b/docs/README.md index 971fa34..a0c4356 100644 --- a/docs/README.md +++ b/docs/README.md @@ -88,9 +88,10 @@ Linux kernel only. Every trusted run has memory, process-count, CPU-time, and sampled net disk-growth limits; the disk limit is not a filesystem quota. Package-network profiles are recorded as configuration only (ADR-0034); no run uses them, and network access remains all-or-nothing. The trusted -`packages fetch` command downloads from declared origins into a private cache; -Linux runs can read only their workspace's cache, and Windows does not expose -it. The limited file broker and the core read/list turn runtime +`packages fetch` command downloads from declared origins into a per-workspace +cache. A selected root is exposed read-only on Linux and Windows; Windows +needs a read-execute grant, and Linux falls back to application storage. The +limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed content without writing to the workspace or creating a checkpoint. diff --git a/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md b/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md index 0ac0ada..e063c97 100644 --- a/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md +++ b/docs/adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md @@ -1,6 +1,6 @@ # 0036: Expose the package fetch cache read-only to Linux runs -- Status: Accepted +- Status: Superseded by ADR-0037 - Date: 2026-11-14 ## Context @@ -85,3 +85,4 @@ container grant. - [Security coding rules](../security-coding-rules.md#process-and-sandbox-boundary) - [Testing standards](../testing-standards.md) - [ADR-0035](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) +- Superseded by [ADR-0037](0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md) diff --git a/docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md b/docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md new file mode 100644 index 0000000..f881413 --- /dev/null +++ b/docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md @@ -0,0 +1,94 @@ +# 0037: Use a per-workspace cache root and a scoped Windows grant + +- Status: Accepted +- Date: 2026-11-14 + +## Context + +[ADR-0036](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) +exposed the application-storage package cache to Linux runs. Windows was left +unexposed because the AppContainer needs an ACL grant to read application +storage, and container grants refuse that storage. + +A configured cache root outside application storage solves that, but a single +global root has two problems on Windows: + +- Granting the root to a workspace's container lets that container read every + workspace's cache beneath it. +- Granting only the per-workspace directory leaves the parent unreadable, and + `cmd` and similar tools can fail to resolve the path. Testing showed that the + AppContainer could read a cache directly under a top-level granted root but + not one beneath the user's private temporary directory. + +The cache root therefore needs to be selected per workspace, and the grant +must cover that workspace's root. + +## Decision + +1. `workspace set-package-cache --revision ` records one + cache root for one workspace. The directory must exist, must not overlap + application storage, must not overlap the development root, and must not + overlap another workspace's cache root. `workspace + clear-package-cache --revision ` removes it. Both use the + settings revision; the journal events are `package_cache_root_set` and + `package_cache_root_cleared`. +2. `packages fetch` writes into the selected workspace root when one is set. + Without one, Linux keeps the application-storage fallback + `/package-cache/`; Windows has no fallback. +3. A run uses the selected root when it exists as a plain directory: + - **Linux:** the directory is added read-only and named by + `OMGCODE_PACKAGE_CACHE`. + - **Windows:** the directory is added read-only and named by + `OMGCODE_PACKAGE_CACHE`. The workspace's container must hold a + read-execute grant on that directory, or the run fails before it starts. + The grant is scoped to that workspace's root; other workspaces use + separate roots. The root's ancestors must be traversable by the + container; use a dedicated top-level directory rather than a user's + private temporary tree. +4. Only the selected directory is exposed. The parent, application storage, + journals, settings, and other workspaces' roots stay outside the run's + view. +5. `run_started` records `package_cache: true` when the run had access. The + field remains optional; runs without a cache omit it. +6. The cache is a directory of fetched files. There is no eviction, + invalidation, freshness check, or power-loss claim. Changing the root does + not move existing files; the operator manages both locations and revokes + any grant on an old root. + +## Alternatives considered + +- **One global cache root.** Rejected: a Windows grant on the root would + expose every workspace's cache to each container. +- **Grant each per-workspace directory beneath one global root.** Rejected: + the parent is unreadable to the container, and path resolution failed in + testing. +- **Grant application storage to the AppContainer.** Rejected: it breaks the + storage overlap rule and exposes journals and settings. +- **Write the cache into the workspace.** Rejected: the trusted fetch would + bypass the replacement contract, and the run could rewrite the cache. +- **Keep the Linux-only exposure.** Rejected now that a scoped cross-platform + design is available. + +## Consequences + +- Windows can expose a fetched cache when the operator selects a reachable + root and grants the container read-execute on it. The run fails rather than + silently omitting the cache when the grant is missing. +- The operator has one more per-workspace setting and must manage the + container grant and the directory. Separate roots preserve cross-workspace + isolation; overlapping roots are refused. +- The Linux application-storage fallback remains for compatibility. A + configured root takes precedence; a stale configured root is not exposed and + the fetch refuses it. +- Tests cover per-workspace set/clear/replay, overlap refusals, the configured + fetch location, Linux read/write/parent denial, Windows access with a grant, + and Windows refusal without one. + +## References + +- [Command execution](../execution.md#trusted-package-fetch) +- [Workspace settings](../workspace-permissions.md) +- [Development tools](../development-tools.md) +- [Security coding rules](../security-coding-rules.md#process-and-sandbox-boundary) +- [Testing standards](../testing-standards.md) +- [ADR-0036](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index b52e6e5..132dcf8 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -50,4 +50,5 @@ meaningful alternative does not need an ADR. | [0033: Bound run disk growth by sampling writable roots](0033-bound-run-disk-growth-by-sampling-writable-roots.md) | Accepted | 2026-11-13 | | [0034: Gate package networking behind enforceable destination control](0034-gate-package-networking-behind-enforceable-destination-control.md) | Accepted | 2026-11-13 | | [0035: Fetch packages through a trusted allowlisted cache](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) | Accepted | 2026-11-13 | -| [0036: Expose the package fetch cache read-only to Linux runs](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) | Accepted | 2026-11-14 | +| [0036: Expose the package fetch cache read-only to Linux runs](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) | Superseded by ADR-0037 | 2026-11-14 | +| [0037: Use a per-workspace cache root and a scoped Windows grant](0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md) | Accepted | 2026-11-14 | diff --git a/docs/development-tools.md b/docs/development-tools.md index c30dc0c..35bbc21 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -130,9 +130,11 @@ allowlist. The is recorded as configuration only (ADR-0034): `workspace package-profile-add/show/remove` store registry origins, but no run accepts a profile, and a proxy or proxy environment variables are not a boundary. The -trusted `packages fetch` command contacts only declared origins and writes a -private cache. On Linux, a run can read only its workspace's cache through -`OMGCODE_PACKAGE_CACHE`; on Windows the cache is not exposed. Tool-specific +trusted `packages fetch` command contacts only declared origins and writes +into the selected per-workspace cache root. A run can read only that root +through `OMGCODE_PACKAGE_CACHE`; Windows needs a read-execute container grant, +and Linux falls back to application storage when no root is selected. +Tool-specific configuration to use that directory is operator work. Registry credentials require a narrow reviewed credential path. Offline tasks must work with available dependencies or explain which download is needed. @@ -164,7 +166,8 @@ builds, disk exhaustion, and hostile build/package scripts. The trusted `packages fetch` command is covered by core and CLI tests. The run-side package-network acceptance case still cannot run: no run accepts a -profile, and no run reads the fetch cache. A future implementation must prove +profile. A run can read the selected cache root, but run-side destination +scoping is still missing. A future implementation must prove that an approved profile reaches its declared registry destinations and rejects every other destination, including direct IP, IPv6, UDP, DNS, and proxy-bypass paths. Model-provider connectivity alone must not enable package @@ -191,7 +194,8 @@ yet: growth; - package downloads through a run's `--network`, and rejection of undeclared destinations, because there is no destination allowlist; the trusted - `packages fetch` path is separate and the run does not read its cache; + `packages fetch` path is separate and the run can read only the selected + cache root, not use run-side package networking; - hostile package scripts beyond the hostile programs. The Java case has not run on either host. The registry case also remains open. diff --git a/docs/execution.md b/docs/execution.md index f9b251f..e459679 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -46,11 +46,11 @@ run bounds the allocated bytes it may add to its writable roots. No portable per-run disk quota exists, so the supervisor measures growth on a separate thread rather than the kernel enforcing a quota. -Version 0.22.0 exposes the fetched-package cache to Linux runs read-only. A -run whose workspace has a cache receives `OMGCODE_PACKAGE_CACHE` and may read -that directory, but not its parent or any other application storage. Windows -runs do not get the cache yet; see -[ADR-0036](adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md). +Version 0.23.0 adds a per-workspace package cache root. A configured root is +exposed read-only on Linux and Windows; Windows requires a read-execute +container grant on that root. Without a configured root, Linux keeps the +application-storage fallback and Windows exposes nothing. See +[ADR-0037](adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md). ## Accepted decisions @@ -263,8 +263,17 @@ It is never a model tool, and the confined run still has no network access. omgcode packages fetch --profile --url --name [--max-bytes <1-1073741824>] [--timeout-secs <1-600>] +omgcode workspace set-package-cache --revision +omgcode workspace clear-package-cache --revision ``` +`set-package-cache` selects one workspace's cache directory. It must exist, +must not overlap application storage or the development root, and must not +overlap another workspace's root. `clear-package-cache` removes the selection +and leaves cached files in place. Without a selected root, Linux uses the +application-storage fallback and Windows has none. A 0.23.0 control journal +cannot be read by 0.22.0. + Before the request it checks: 1. The workspace is registered and its live `task_network` preference is @@ -284,7 +293,8 @@ and its body is streamed, hashed with SHA-256, and stopped if it passes the byte limit. The file is written as a private `.partial-` entry, synced, and -renamed to `/package-cache//`. Existing +renamed into the selected workspace cache root, or into +`/package-cache//` when no root is selected. Existing names are never overwritten. The cache makes no power-loss claim. The control journal records `package_fetch_started` before the request and `package_fetch_finished` after it; both preserve the settings revision. They @@ -293,15 +303,18 @@ text), the cache name, limits, HTTP status, byte count, and content digest. A failure records a controlled reason. An abandoned fetch leaves its start record without a finish; nothing retries automatically. -The run does not contact the registry itself. On Linux, when -`/package-cache/` exists as a plain directory, the run -adds only that directory to its read-only rules and sets -`OMGCODE_PACKAGE_CACHE` to it. The parent `package-cache` directory and the -rest of the data root stay outside the run's view, and the run cannot write -the cache. Windows does not expose the cache because the AppContainer cannot -read application storage without an ACL grant, and container grants refuse -that storage. Tool-specific use of the directory is operator configuration. -Registry credentials remain unsupported. +The run does not contact the registry itself. When the workspace cache exists +as a plain directory, the run adds only that directory to its read-only rules +and sets `OMGCODE_PACKAGE_CACHE` to it. The parent, application storage, +journals, settings, and other workspaces' roots stay outside the run's view, +and the run cannot write the cache. On Windows the selected root requires a +read-execute container grant on that directory; without it the run fails +before the program starts. Without a selected root, Linux uses the +application-storage fallback and Windows exposes nothing. The root's ancestors +must be traversable by the container, so use a dedicated top-level directory +rather than a user's private temporary tree. Tool-specific use of the +directory is operator configuration. Registry credentials remain unsupported. +`workspace status` lists selected roots under `package_cache_roots`. ## Container grants @@ -340,6 +353,11 @@ Rules: - The granted directory must still be the recorded one, by volume and file identity. A moved or replaced directory cannot be revoked through OMGCode until it is back at its recorded path. +- A per-workspace package cache root outside the development root and + application storage is a valid read-execute grant target. Grant that root, + not a shared parent. The grant is container-wide, so use separate roots for + workspaces that must stay isolated. The container must be able to traverse + the root's ancestors; a dedicated top-level directory is recommended. - Grants work only on Windows. Elsewhere `container-grant` fails and records nothing. @@ -465,8 +483,8 @@ entries, the runner-owned variables below, and the profile's variables. | Platform | Runner-owned variables | Read-only | Read-write | | --- | --- | --- | --- | -| Linux | `HOME`, `TMPDIR`, and `XDG_CACHE_HOME`, all set to `/run-scratch/` (mode 0700, removed after the run), and, when the workspace cache exists, `OMGCODE_PACKAGE_CACHE` set to `/package-cache/` | Profile roots, `/dev/zero`, `/dev/random`, `/dev/urandom`, the workspace's [package cache](#trusted-package-fetch) when it exists, and, with `--network`, the [network support paths](#network-access) | The workspace, the scratch directory, `/dev/null` | -| Windows | `LOCALAPPDATA`, `SystemRoot`, `windir`, and `HOME` and `USERPROFILE` set to the container's `AC` folder. Windows then sets `TEMP` and `TMP` inside it. The package cache is not exposed | Profile roots, checked against their live ACLs | The workspace, through its grant | +| Linux | `HOME`, `TMPDIR`, and `XDG_CACHE_HOME`, all set to `/run-scratch/` (mode 0700, removed after the run), and, when the workspace cache exists, `OMGCODE_PACKAGE_CACHE` set to the selected root or the application-storage fallback | Profile roots, `/dev/zero`, `/dev/random`, `/dev/urandom`, the workspace's [package cache](#trusted-package-fetch) when it exists, and, with `--network`, the [network support paths](#network-access) | The workspace, the scratch directory, `/dev/null` | +| Windows | `LOCALAPPDATA`, `SystemRoot`, `windir`, and `HOME` and `USERPROFILE` set to the container's `AC` folder. Windows then sets `TEMP` and `TMP` inside it. When a granted package cache root exists, `OMGCODE_PACKAGE_CACHE` is set to it | Profile roots, checked against their live ACLs; the package cache root, checked against its grant | The workspace, through its grant | Linux runs use `PairsOnly` sockets unless host services were selected. Runs have no IP networking unless `--network` was passed. Windows @@ -926,15 +944,16 @@ These remain true after C6: boundary: a hostile tree can connect directly. - **Package fetch limits.** The fetch is trusted-CLI only. It sends no credentials, follows no redirects, ignores proxy variables, and uses the - system TLS store. The cache is private application storage; only the - per-workspace subtree is exposed to Linux runs, read-only. It makes no - power-loss claim. Tests use loopback HTTP; a live HTTPS registry is not - qualified. -- **Package cache exposure is Linux-only.** A Linux run receives - `OMGCODE_PACKAGE_CACHE` and may read that directory, but not its parent, - journals, settings, or another workspace's cache. Windows does not expose - it. There is no invalidation, eviction, or freshness check, and configuring - a toolchain to use the directory is operator work. + system TLS store. The cache is the selected per-workspace root or, on Linux, + the application-storage fallback. It makes no power-loss claim. Tests use + loopback HTTP; a live HTTPS registry is not qualified. +- **Package cache exposure.** A run receives `OMGCODE_PACKAGE_CACHE` when the + workspace cache exists as a plain directory, and may read only that + directory. On Windows the selected root needs a read-execute container grant + and traversable ancestors, or the run fails before it starts. Linux falls + back to application storage when no root is selected; Windows exposes + nothing. There is no invalidation, eviction, or freshness check, and + configuring a toolchain to use the directory is operator work. - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -988,12 +1007,12 @@ These remain true after C6: | C8 (contract only, 0.19.0) | Package-network profile contract and implementation gate | Done as a contract: see [package-network profile](#package-network-profile-contract-only) and ADR-0034. No destination enforcement. | | C9 (0.20.0) | Package-network profile records | Done as configuration: `workspace package-profile-add/show/remove` and the control journal events. No run accepts a profile. | | C10 (0.21.0) | Trusted allowlisted package fetch | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0035. The run remains offline. | -| C11 (0.22.0) | Read-only package cache for Linux runs | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0036. Windows does not expose the cache. | +| C11 (0.22.0) | Read-only package cache for Linux runs | Superseded by C12: Linux exposure moved to the per-workspace root, with an application-storage fallback. | +| C12 (0.23.0) | Per-workspace package cache root and scoped Windows grant | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0037. Windows needs a read-execute grant on the workspace root. | Later work needs its own decisions: -- a Windows package-cache root and grant design, registry credentials, and - development-server networking; +- registry credentials and development-server networking; - a model-callable command tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/platform-support.md b/docs/platform-support.md index 3830e37..962e4b6 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -22,7 +22,7 @@ containment. | Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | -| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a private cache. Linux runs read only their workspace's cache; Windows does not expose it (ADR-0034, ADR-0035, ADR-0036) ([fetch](execution.md#trusted-package-fetch)) | +| Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a per-workspace cache root. The root is exposed read-only on Linux and Windows; Windows needs a read-execute container grant and traversable ancestors, and Linux falls back to application storage when no root is selected (ADR-0034, ADR-0035, ADR-0037) ([fetch](execution.md#trusted-package-fetch)) | | Trusted runs | `omgcode run` with operator-declared toolchain profiles on Linux and Windows. Acceptance passed for Rust, Python, Node, C/C++, and Go on both hosts; Java has not run ([execution](execution.md#known-limits)) | | Linux broker prerequisites | Linux 5.6 or later for required `openat2`; `/proc/self/fd` must be available for pinned-file reads; unsupported features fail closed | | Checkpoint preparation/storage | Core API on Linux and Windows. Linux requires openat2/procfs, current-user mode0700 directories/mode0600 files, native birth-time metadata and real file/directory sync. Windows requires NTFS, exact protected per-user DACLs, and a trusted data root (ADR-0023) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 360390b..f82b479 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -234,9 +234,11 @@ crate. contact only a declared origin and path prefix, must disable redirects and proxy variables, send no credentials, cap and hash the response, and write only the private per-workspace cache. Record the intent and outcome without - the URL text. A Linux run may read only the per-workspace cache subtree; do - not expose its parent, journals, settings, or another workspace. Do not - expose the cache on a platform that cannot enforce the same boundary. + the URL text. A run may read only the selected per-workspace cache root; do + not expose its parent, journals, settings, or another workspace's root. On + Windows the root needs a read-execute container grant, and overlapping cache + roots are refused. Do not expose the cache on a platform that cannot + enforce the same boundary. - Assemble and validate a complete structured tool call before dispatch. Validate names, arguments, limits, session scope, and provider call identity. A provider adapter must parse provider JSON strictly; the core runtime then diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 3f8aca1..aeebfae 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -143,7 +143,7 @@ As the relevant components are implemented, include: | Processes | Descendant escape attempts, limits, cleanup, startup failure | | Disk limits | Sampled growth ends the whole run as `disk`, baseline excludes prior content, links and reparse points are not followed, the ceiling stops a scan early, unreadable or oversized roots fail closed | | Networking | Disabled egress, host-local access, redirects, provider routing | -| Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. Linux cache exposure covers read access, write denial, parent denial, the reserved variable, and the `package_cache` journal field; Windows covers the variable's absence. No run accepts a profile. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md), [ADR-0036](adr/0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md)) | +| Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. Cache roots cover per-workspace set/clear/replay, overlap refusals, the configured fetch location, Linux read/write/parent denial, Windows access with a scoped grant, and Windows refusal without one. No run accepts a profile. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md), [ADR-0037](adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | diff --git a/docs/workspace-permissions.md b/docs/workspace-permissions.md index 638855a..4910933 100644 --- a/docs/workspace-permissions.md +++ b/docs/workspace-permissions.md @@ -120,6 +120,8 @@ zero-based sequence, UTC timestamp, global revision, and tagged `action`: | `package_profile_removed` | Remove a package-network profile; increment revision | | `package_fetch_started` | Trusted package-fetch intent; preserve revision | | `package_fetch_finished` | Trusted package-fetch outcome; preserve revision | +| `package_cache_root_set` | Select one workspace's package cache root; increment revision | +| `package_cache_root_cleared` | Clear one workspace's package cache root; increment revision | Operational file checks do not append `policy_checked`. They use current settings and their separate [operation journal](file-access.md). This prevents @@ -195,6 +197,20 @@ the URL text), the cache name, limits, HTTP status, byte count, and content digest. A failed fetch records a controlled reason; an abandoned fetch leaves its start event. A control journal written by 0.21.0 cannot be read by 0.20.0. +## Package cache roots + +`workspace set-package-cache --revision ` selects one +workspace's fetched-package cache directory. It must exist, must not overlap +application storage or the development root, and must not overlap another +workspace's cache root. `workspace clear-package-cache +--revision ` removes the selection and leaves cached files in place. Both +use the expected revision and increment it through `package_cache_root_set` +and `package_cache_root_cleared`. `workspace status` lists selected roots under +`package_cache_roots` and omits the field until one exists. A control journal +written by 0.23.0 cannot be read by 0.22.0. The +[execution guide](execution.md#trusted-package-fetch) owns the fetch, exposure, +and grant rules. + ## Task network `workspace permissions --revision --task-network true` lets a From 1f411b4d9c52de2733ec331e9cdebb0ca9208cb3 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 08:40:04 +0000 Subject: [PATCH 08/17] feat: record provider profiles and per-call approvals Add operator-declared provider profiles with a name, kind, and authentication mode. Profiles store no endpoint, account, token, or other credential, and no adapter or login uses them. Add trusted approval records bound to a session, workspace, operation, request digest, and settings revision. Requests expire and are consumed once; a settings change invalidates them. The CLI consume command executes nothing, and no model tool consumes an approval yet. Version 0.24.0. See ADR-0038 and ADR-0039. Co-Authored-By: Claude Code --- AGENTS.md | 4 +- CHANGELOG.md | 17 + Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 26 +- README.md | 8 +- crates/omgcode-cli/src/approvals_cli.rs | 204 ++++++++ crates/omgcode-cli/src/control_cli.rs | 70 ++- crates/omgcode-cli/src/main.rs | 10 + crates/omgcode-cli/tests/control_workflow.rs | 269 ++++++++++- crates/omgcode-core/src/control.rs | 58 +++ crates/omgcode-core/src/control/approval.rs | 449 ++++++++++++++++++ .../src/control/approval/tests.rs | 230 +++++++++ crates/omgcode-core/src/control/provider.rs | 296 ++++++++++++ .../src/control/provider/tests.rs | 116 +++++ docs/README.md | 4 +- ...d-provider-profiles-without-credentials.md | 74 +++ ...-with-bound-single-use-approval-records.md | 87 ++++ docs/adr/index.md | 2 + docs/agent-instructions.md | 18 + docs/provider-authentication.md | 16 + docs/security-coding-rules.md | 10 + docs/testing-standards.md | 2 + docs/workspace-permissions.md | 31 ++ 24 files changed, 1992 insertions(+), 17 deletions(-) create mode 100644 crates/omgcode-cli/src/approvals_cli.rs create mode 100644 crates/omgcode-core/src/control/approval.rs create mode 100644 crates/omgcode-core/src/control/approval/tests.rs create mode 100644 crates/omgcode-core/src/control/provider.rs create mode 100644 crates/omgcode-core/src/control/provider/tests.rs create mode 100644 docs/adr/0038-record-provider-profiles-without-credentials.md create mode 100644 docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md diff --git a/AGENTS.md b/AGENTS.md index b8bd257..6d48457 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,9 @@ filesystem quota. Package-network profiles are recorded as configuration only; no run uses them. The trusted `packages fetch` command downloads from declared origins into a per-workspace cache. A selected root is exposed read-only on Linux and Windows; Windows needs a read-execute container grant, and Linux -falls back to application storage. Trusted CLI +falls back to application storage. Provider profiles and trusted single-use +approval records are configuration and authorization records only; no adapter +or model tool uses them. Trusted CLI commands record, apply, and revoke Windows container ACL grants. Follow the [execution contract](docs/execution.md). The bundled web interface and most planned features are not implemented. diff --git a/CHANGELOG.md b/CHANGELOG.md index f91a05e..9922a03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,23 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.24.0 records provider profiles and trusted per-call approvals. + See ADR-0038 and ADR-0039. + - **Provider profiles:** `workspace provider-profile-add/show/remove` record + a name, provider kind, and authentication mode (`subscription`, + `api_key`, or `none`). Subscription is limited to OpenAI and Anthropic; + local providers use `none`. No endpoint, account, token, or credential is + stored, and no adapter or login uses a profile. `capabilities` reports + `provider_profiles: true` and `provider_adapters: false`. + - **Approvals:** `approvals request/list/show/approve/deny/consume` manage + trusted, single-use records bound to a session, workspace, operation, + exact request digest, and settings revision. Records expire in 60 to 3600 + seconds; a settings change invalidates them; no argument text is stored. + The CLI consume command executes nothing, and no model tool consumes an + approval yet. + - **Records:** `provider_profile_added`, `provider_profile_removed`, + `approval_requested`, `approval_decided`, and `approval_consumed` in the + control journal. A 0.24.0 journal cannot be read by 0.23.0. - Version 0.23.0 adds a per-workspace package cache root and scoped Windows access. See ADR-0037. - **Commands:** `workspace set-package-cache diff --git a/Cargo.lock b/Cargo.lock index 5574255..c9b01e8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -672,7 +672,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.23.0" +version = "0.24.0" dependencies = [ "clap", "directories", @@ -685,7 +685,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.23.0" +version = "0.24.0" dependencies = [ "libc", "omgcode-platform", @@ -701,7 +701,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.23.0" +version = "0.24.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 7996307..95d1c27 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.23.0" +version = "0.24.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index e4bd809..f164761 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -64,9 +64,12 @@ This is a resume guide, not a replacement for the owning contracts in package-network profile records, **Phase C10**, version **0.21.0**, with the trusted allowlisted package fetch and private cache (ADR-0035), and **Phase C11**, version **0.22.0**, with read-only Linux run access to that - cache (ADR-0036), and **Phase C12**, version **0.23.0**, with per-workspace - cache roots and scoped Windows access (ADR-0037). It is stacked on C7 at - `0426e42`. No run accepts a profile or has destination-scoped networking. + cache (ADR-0036), **Phase C12**, version **0.23.0**, with per-workspace + cache roots and scoped Windows access (ADR-0037), and **Phase C13**, version + **0.24.0**, with provider-profile records and trusted per-call approvals + (ADR-0038, ADR-0039). It is stacked on C7 at `0426e42`. No run accepts a + profile or has destination-scoped networking; no provider adapter or model + tool is enabled. Implemented today: @@ -149,6 +152,11 @@ Implemented today: named by `OMGCODE_PACKAGE_CACHE`. Windows requires a read-execute container grant on the root; Linux falls back to application storage when no root is selected. Overlapping roots are refused. +- Provider profiles record connection shapes without credentials or adapters + (ADR-0038). Trusted approval records bind a future model-tool call to a + session, workspace, operation, request digest, and settings revision, expire, + and are consumed once (ADR-0039). Neither enables a provider connection or a + model tool. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -522,11 +530,19 @@ on Windows, and trusted CLI commands as the first caller. See storage and the development root; fetch and run use it; Windows needs a read-execute grant on that root. See [ADR-0037](docs/adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md). +- **C13 (this branch, version 0.24.0):** provider-profile records and trusted + per-call approval records. Profiles store only a name, kind, and + authentication mode; no credential, endpoint, adapter, or login exists. + Approvals are bound, expiring, single-use records; no model tool consumes + one yet. See + [ADR-0038](docs/adr/0038-record-provider-profiles-without-credentials.md) and + [ADR-0039](docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). Next decisions, not yet scheduled: -- registry credentials and development-server networking; -- a model-callable command tool with per-call approval. +- a credential service, provider adapters, and subscription/API-key login; +- a model-callable command tool that consumes the approval record; +- registry credentials and development-server networking. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index de9a9b7..a5ebc2f 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,11 @@ directory grants. > declared origins into a private per-workspace cache. A selected cache root > is exposed read-only on Linux and Windows; Windows needs a read-execute > container grant, and Linux falls back to application storage when no root is -> selected. Runs have memory, process-count, CPU-time, and sampled disk-growth -> limits; the disk limit is not a filesystem quota. See -> [command execution](docs/execution.md#tree-limits). +> selected. Provider profiles record connection shapes, and trusted +> single-use approval records prepare per-call model-tool consent; neither +> enables an adapter, login, or model tool. Runs have memory, process-count, +> CPU-time, and sampled disk-growth limits; the disk limit is not a filesystem +> quota. See [command execution](docs/execution.md#tree-limits). ## Goals diff --git a/crates/omgcode-cli/src/approvals_cli.rs b/crates/omgcode-cli/src/approvals_cli.rs new file mode 100644 index 0000000..0236533 --- /dev/null +++ b/crates/omgcode-cli/src/approvals_cli.rs @@ -0,0 +1,204 @@ +//! Trusted operator approval commands. +#![forbid(unsafe_code)] + +use std::path::Path; +use std::str::FromStr; +use std::thread; +use std::time::{Duration, Instant}; + +use clap::{Args, Subcommand}; +use omgcode_core::control::{ + ApprovalBinding, ApprovalDeclaration, ApprovalOperation, ControlError, ControlStore, now_unix, +}; +use omgcode_core::policy::WorkspaceId; +use serde_json::json; +use uuid::Uuid; + +use crate::{CliError, print_json}; + +/// Inspect, decide, or consume trusted per-call approvals. +#[derive(Subcommand)] +pub(crate) enum ApprovalsCommand { + /// Record a pending approval request. Nothing executes. + Request(RequestArgs), + /// List retained approvals and their current states. + List, + /// Show one approval. + Show { approval: Uuid }, + /// Approve a pending, unexpired request. + Approve { approval: Uuid }, + /// Deny a pending, unexpired request. + Deny { approval: Uuid }, + /// Consume an approved request once. This executes nothing. + Consume(ConsumeArgs), +} + +#[derive(Args)] +pub(crate) struct RequestArgs { + /// The session the future call belongs to (version 4 UUID). + #[arg(long)] + session: Uuid, + /// The registered workspace the future call targets. + #[arg(long)] + workspace: String, + /// command, file_write, git_push, or network. + #[arg(long)] + operation: String, + /// SHA-256 of the exact future call, as 64 lowercase hex characters. + #[arg(long)] + digest: String, + /// Operator-facing context. At most 256 bytes; never include secrets. + #[arg(long)] + summary: String, + /// Lifetime in seconds (60 to 3600). + #[arg(long, default_value_t = 900)] + ttl_secs: u64, +} + +#[derive(Args)] +pub(crate) struct ConsumeArgs { + approval: Uuid, + /// The session the call belongs to. + #[arg(long)] + session: Uuid, + /// The workspace the call targets. + #[arg(long)] + workspace: String, + /// command, file_write, git_push, or network. + #[arg(long)] + operation: String, + /// SHA-256 of the exact call. + #[arg(long)] + digest: String, +} + +const CONTROL_WAIT: Duration = Duration::from_secs(10); +const CONTROL_POLL: Duration = Duration::from_millis(20); + +/// Run one approval command. +pub(crate) fn run(action: ApprovalsCommand, data_root: &Path) -> Result<(), CliError> { + match action { + ApprovalsCommand::Request(args) => request(args, data_root), + ApprovalsCommand::List => { + let store = open(data_root)?; + let now = now_unix(); + print_json(&json!({ + "now": now, + "approvals": store.approval_statuses(now), + })) + } + ApprovalsCommand::Show { approval } => { + let store = open(data_root)?; + let status = store + .approval_status(approval, now_unix()) + .ok_or_else(|| approval_error(ControlError::UnknownApproval))?; + print_json(&json!({ "approval": status })) + } + ApprovalsCommand::Approve { approval } => decide(approval, true, data_root), + ApprovalsCommand::Deny { approval } => decide(approval, false, data_root), + ApprovalsCommand::Consume(args) => consume(args, data_root), + } +} + +fn request(args: RequestArgs, data_root: &Path) -> Result<(), CliError> { + let workspace_id = parse_workspace(&args.workspace)?; + let operation = ApprovalOperation::parse(&args.operation).ok_or_else(|| { + CliError::new( + "configuration", + "Operation must be command, file_write, git_push, or network", + ) + })?; + let mut store = open(data_root)?; + let status = store + .request_approval( + &ApprovalDeclaration { + session_id: args.session, + workspace_id, + operation, + request_sha256: args.digest, + summary: args.summary, + ttl_secs: args.ttl_secs, + }, + now_unix(), + ) + .map_err(approval_error)?; + print_json(&json!({ "approval": status })) +} + +fn decide(approval: Uuid, approved: bool, data_root: &Path) -> Result<(), CliError> { + let mut store = open(data_root)?; + let now = now_unix(); + store + .decide_approval(approval, approved, now) + .map_err(approval_error)?; + let status = store + .approval_status(approval, now) + .ok_or_else(|| approval_error(ControlError::UnknownApproval))?; + print_json(&json!({ + "decision": if approved { "approved" } else { "denied" }, + "approval": status, + })) +} + +fn consume(args: ConsumeArgs, data_root: &Path) -> Result<(), CliError> { + let workspace_id = parse_workspace(&args.workspace)?; + let operation = ApprovalOperation::parse(&args.operation).ok_or_else(|| { + CliError::new( + "configuration", + "Operation must be command, file_write, git_push, or network", + ) + })?; + let mut store = open(data_root)?; + store + .consume_approval( + args.approval, + &ApprovalBinding { + session_id: args.session, + workspace_id, + operation, + request_sha256: args.digest, + }, + now_unix(), + ) + .map_err(approval_error)?; + print_json(&json!({ + "consumed": args.approval, + "approval": store.approval_status(args.approval, now_unix()), + })) +} + +fn parse_workspace(text: &str) -> Result { + WorkspaceId::from_str(text) + .map_err(|_| CliError::new("configuration", "Invalid workspace identifier")) +} + +/// Open existing settings, waiting briefly for another command's lock. +fn open(data_root: &Path) -> Result { + let until = Instant::now() + CONTROL_WAIT; + loop { + match ControlStore::open_existing(data_root) { + Ok(Some(store)) => return Ok(store), + Ok(None) => { + return Err(CliError::new( + "control", + "Workspace control is not initialized", + )); + } + Err(ControlError::Busy) if Instant::now() < until => thread::sleep(CONTROL_POLL), + Err(error) => return Err(control_error(error)), + } + } +} + +fn control_error(error: ControlError) -> CliError { + CliError::new("control", error.to_string()) +} + +fn approval_error(error: ControlError) -> CliError { + match error { + ControlError::ApprovalRefused(_) | ControlError::UnknownApproval => { + CliError::new("approval", error.to_string()) + } + other => control_error(other), + } +} diff --git a/crates/omgcode-cli/src/control_cli.rs b/crates/omgcode-cli/src/control_cli.rs index 8fb760b..7cbc394 100644 --- a/crates/omgcode-cli/src/control_cli.rs +++ b/crates/omgcode-cli/src/control_cli.rs @@ -4,7 +4,8 @@ use clap::{Args, Subcommand, ValueEnum}; use omgcode_core::control::{ - ContainerGrantAccess, ControlError, ControlStore, PackageProfileDeclaration, ProfileDeclaration, + ContainerGrantAccess, ControlError, ControlStore, PackageProfileDeclaration, + ProfileDeclaration, ProviderProfileDeclaration, }; use omgcode_core::policy::{Operation, PermissionSet, PolicyRequest, WorkspaceId}; use omgcode_core::run; @@ -87,6 +88,31 @@ pub(crate) enum WorkspaceCommand { #[arg(long)] revision: u64, }, + /// Record a provider connection shape. No credential or adapter is used. + ProviderProfileAdd(ProviderProfileAddArgs), + /// Show one recorded provider profile. + ProviderProfileShow { name: String }, + /// Remove a provider profile. + ProviderProfileRemove { + name: String, + #[arg(long)] + revision: u64, + }, +} + +#[derive(Args)] +pub(crate) struct ProviderProfileAddArgs { + /// The profile name: ASCII letters, digits, '.', '-', or '_'. + name: String, + /// One of: openai, anthropic, ollama_local, ollama_cloud, open_router, + /// lm_studio. + #[arg(long)] + kind: String, + /// One of: subscription, api_key, none. + #[arg(long)] + auth: String, + #[arg(long)] + revision: u64, } #[derive(Args)] @@ -303,6 +329,29 @@ pub(crate) fn run(action: WorkspaceCommand, data_root: &Path) -> Result<(), CliE stop_withdrawn_runs(data_root, &[])?; print_json(&output) } + WorkspaceCommand::ProviderProfileAdd(args) => provider_profile_add(args, data_root), + WorkspaceCommand::ProviderProfileShow { name } => { + let store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile = store + .provider_profile(&name) + .ok_or_else(|| control_error(ControlError::UnknownProvider))?; + print_json(&json!({ "provider_profile": profile })) + } + WorkspaceCommand::ProviderProfileRemove { name, revision } => { + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile_id = store + .remove_provider_profile(&name, revision) + .map_err(control_error)?; + let output = json!({ + "removed_provider_profile_id": profile_id, + "snapshot": store.snapshot(), + }); + drop(store); + stop_withdrawn_runs(data_root, &[])?; + print_json(&output) + } WorkspaceCommand::ContainerRevoke { grant } => { let mut store = open_existing(data_root)? .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; @@ -402,6 +451,25 @@ fn package_profile_add(args: PackageProfileAddArgs, data_root: &Path) -> Result< })) } +fn provider_profile_add(args: ProviderProfileAddArgs, data_root: &Path) -> Result<(), CliError> { + let mut store = open_existing(data_root)? + .ok_or_else(|| CliError::new("control", "Workspace control is not initialized"))?; + let profile = store + .add_provider_profile( + &ProviderProfileDeclaration { + name: args.name, + kind: args.kind, + auth: args.auth, + }, + args.revision, + ) + .map_err(control_error)?; + print_json(&json!({ + "provider_profile_id": profile.id(), + "snapshot": store.snapshot(), + })) +} + fn set_permissions(args: PermissionsArgs, data_root: &Path) -> Result<(), CliError> { if args.read.is_none() && args.write.is_none() diff --git a/crates/omgcode-cli/src/main.rs b/crates/omgcode-cli/src/main.rs index 6ecb5c1..c3ef5f1 100644 --- a/crates/omgcode-cli/src/main.rs +++ b/crates/omgcode-cli/src/main.rs @@ -1,6 +1,7 @@ //! Developer CLI for the first OMGCode core prototype. #![forbid(unsafe_code)] +mod approvals_cli; mod control_cli; mod file_cli; mod model_tools; @@ -74,6 +75,11 @@ enum Command { #[command(subcommand)] action: packages_cli::PackagesCommand, }, + /// Inspect, decide, or consume trusted per-call approvals. + Approvals { + #[command(subcommand)] + action: approvals_cli::ApprovalsCommand, + }, } #[derive(Subcommand)] @@ -237,6 +243,9 @@ fn run(cli: Cli) -> Result<(), CliError> { "package_network_profiles": true, "package_network_enforcement": false, "package_fetch": true, + "provider_profiles": true, + "provider_adapters": false, + "approvals": true, "process_execution": if RUN_SUPPORTED { serde_json::Value::from("trusted_cli_only") } else { @@ -301,6 +310,7 @@ fn run(cli: Cli) -> Result<(), CliError> { Command::Run(args) => run_cli::run(args, &data_root(cli.data_dir)?), Command::Runs { action } => run_cli::runs(action, &data_root(cli.data_dir)?), Command::Packages { action } => packages_cli::run(action, &data_root(cli.data_dir)?), + Command::Approvals { action } => approvals_cli::run(action, &data_root(cli.data_dir)?), } } diff --git a/crates/omgcode-cli/tests/control_workflow.rs b/crates/omgcode-cli/tests/control_workflow.rs index c533a7d..9bc72a7 100644 --- a/crates/omgcode-cli/tests/control_workflow.rs +++ b/crates/omgcode-cli/tests/control_workflow.rs @@ -13,8 +13,8 @@ use uuid::Uuid; #[cfg(unix)] use support::CLI_DEADLINE; use support::{ - HANG_FIXTURE_ENV, assert_control_error, assert_success, json_output, path_arg, run_cli, - run_with_deadline, + HANG_FIXTURE_ENV, assert_control_error, assert_error_code, assert_success, json_output, + path_arg, run_cli, run_with_deadline, }; /// Park only when the timeout regression launches this test in a child process. @@ -451,6 +451,9 @@ fn capabilities_report_configuration_only_policy_and_trusted_runs_only() { assert_eq!(capabilities["package_network_profiles"], true); assert_eq!(capabilities["package_network_enforcement"], false); assert_eq!(capabilities["package_fetch"], true); + assert_eq!(capabilities["provider_profiles"], true); + assert_eq!(capabilities["provider_adapters"], false); + assert_eq!(capabilities["approvals"], true); if runs { assert_eq!(capabilities["process_execution"], "trusted_cli_only"); } else { @@ -587,6 +590,268 @@ fn package_profiles_are_configuration_only_and_revisioned() { assert_control_error(&output); } +/// Provider profiles record only a connection shape and authentication mode; +/// they hold no credential and enable no adapter. +#[test] +fn provider_profiles_are_configuration_only_and_revisioned() { + let temporary = TempDir::new().expect("temporary directory"); + let data_root = temporary.path().join("application-data"); + let development_root = temporary.path().join("development"); + fs::create_dir_all(&development_root).expect("development root"); + let revision = set_root(&data_root, &development_root)["revision"] + .as_u64() + .expect("revision"); + + let output = run_cli( + &data_root, + &[ + "workspace", + "provider-profile-add", + "work", + "--kind", + "openai", + "--auth", + "subscription", + "--revision", + &revision.to_string(), + ], + ); + assert_success(&output); + let added = json_output(&output); + assert!(added["provider_profile_id"].as_str().is_some()); + assert_eq!(added["snapshot"]["provider_profiles"][0]["name"], "work"); + assert_eq!(added["snapshot"]["provider_profiles"][0]["kind"], "openai"); + assert_eq!( + added["snapshot"]["provider_profiles"][0]["auth"], + "subscription" + ); + let revision = added["snapshot"]["revision"] + .as_u64() + .expect("revision after add"); + + let output = run_cli(&data_root, &["workspace", "provider-profile-show", "WORK"]); + assert_success(&output); + let shown = json_output(&output); + assert_eq!(shown["provider_profile"]["name"], "work"); + assert_eq!(shown["provider_profile"]["kind"], "openai"); + assert_eq!(shown["provider_profile"]["auth"], "subscription"); + + let output = run_cli( + &data_root, + &[ + "workspace", + "provider-profile-add", + "invalid", + "--kind", + "ollama_local", + "--auth", + "api_key", + "--revision", + &revision.to_string(), + ], + ); + assert_control_error(&output); + let output = run_cli( + &data_root, + &[ + "workspace", + "provider-profile-add", + "WORK", + "--kind", + "anthropic", + "--auth", + "api_key", + "--revision", + &revision.to_string(), + ], + ); + assert_control_error(&output); + + let output = run_cli( + &data_root, + &[ + "workspace", + "provider-profile-remove", + "work", + "--revision", + "0", + ], + ); + assert_control_error(&output); + let output = run_cli( + &data_root, + &[ + "workspace", + "provider-profile-remove", + "work", + "--revision", + &revision.to_string(), + ], + ); + assert_success(&output); + assert!( + json_output(&output)["snapshot"] + .get("provider_profiles") + .is_none() + ); + let output = run_cli(&data_root, &["workspace", "provider-profile-show", "work"]); + assert_control_error(&output); +} + +/// Approvals are requested, decided, and consumed once; a denied or replayed +/// request is refused. No operation executes. +#[test] +fn approvals_are_requested_decided_and_consumed_once() { + let temporary = TempDir::new().expect("temporary directory"); + let data_root = temporary.path().join("application-data"); + let development_root = temporary.path().join("development"); + let workspace = development_root.join("workspace"); + fs::create_dir_all(&workspace).expect("workspace"); + let revision = set_root(&data_root, &development_root)["revision"] + .as_u64() + .expect("revision"); + let workspace_id = register(&data_root, &workspace, revision); + let session = Uuid::new_v4().to_string(); + let digest = "a".repeat(64); + + let output = run_cli( + &data_root, + &[ + "approvals", + "request", + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + &digest, + "--summary", + "Run the project build", + "--ttl-secs", + "900", + ], + ); + assert_success(&output); + let approval = json_output(&output)["approval"].clone(); + let approval_id = approval["id"].as_str().expect("approval id").to_owned(); + assert_eq!(approval["state"], "pending"); + + let output = run_cli(&data_root, &["approvals", "list"]); + assert_success(&output); + assert_eq!(json_output(&output)["approvals"][0]["id"], approval_id); + + let output = run_cli(&data_root, &["approvals", "approve", &approval_id]); + assert_success(&output); + assert_eq!(json_output(&output)["decision"], "approved"); + assert_eq!(json_output(&output)["approval"]["state"], "approved"); + + let output = run_cli( + &data_root, + &[ + "approvals", + "consume", + &approval_id, + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + &digest, + ], + ); + assert_success(&output); + assert_eq!(json_output(&output)["approval"]["state"], "consumed"); + let output = run_cli( + &data_root, + &[ + "approvals", + "consume", + &approval_id, + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + &digest, + ], + ); + assert_error_code(&output, "approval"); + + let denied_digest = "b".repeat(64); + let output = run_cli( + &data_root, + &[ + "approvals", + "request", + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + &denied_digest, + "--summary", + "Second request", + "--ttl-secs", + "900", + ], + ); + assert_success(&output); + let denied_id = json_output(&output)["approval"]["id"] + .as_str() + .expect("denied id") + .to_owned(); + let output = run_cli(&data_root, &["approvals", "deny", &denied_id]); + assert_success(&output); + assert_eq!(json_output(&output)["decision"], "denied"); + let output = run_cli( + &data_root, + &[ + "approvals", + "consume", + &denied_id, + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + &denied_digest, + ], + ); + assert_error_code(&output, "approval"); + + let output = run_cli( + &data_root, + &[ + "approvals", + "request", + "--session", + &session, + "--workspace", + &workspace_id, + "--operation", + "command", + "--digest", + "not-a-digest", + "--summary", + "Invalid", + ], + ); + assert_error_code(&output, "approval"); + let missing = Uuid::new_v4(); + let output = run_cli(&data_root, &["approvals", "show", &missing.to_string()]); + assert_error_code(&output, "approval"); +} + fn register(data_root: &Path, workspace: &Path, revision: u64) -> String { let output = run_cli( data_root, diff --git a/crates/omgcode-core/src/control.rs b/crates/omgcode-core/src/control.rs index 73ca1d4..129294a 100644 --- a/crates/omgcode-core/src/control.rs +++ b/crates/omgcode-core/src/control.rs @@ -22,9 +22,17 @@ use crate::policy::{ use crate::storage::{self, StorageError}; use crate::workspace::DirectoryRecord; +mod approval; mod container; mod package; mod profile; +mod provider; + +pub use approval::{ + ApprovalBinding, ApprovalDecision, ApprovalDeclaration, ApprovalOperation, ApprovalRequest, + ApprovalState, ApprovalStatus, MAX_APPROVAL_SUMMARY_BYTES, MAX_APPROVAL_TTL_SECS, + MAX_APPROVALS, MAX_PENDING_APPROVALS, MIN_APPROVAL_TTL_SECS, now_unix, +}; pub use container::{ ContainerGrant, ContainerGrantAccess, ContainerGrantState, ContainerGrantStatus, @@ -44,6 +52,10 @@ pub use profile::{ ProfilePlatform, ProfileStatus, ProfileVariable, RESERVED_VARIABLES, ToolchainProfile, is_reserved_variable, valid_profile_name, }; +pub use provider::{ + MAX_PROVIDER_PROFILES, ProviderAuth, ProviderKind, ProviderProfile, ProviderProfileDeclaration, + ProviderProfileStatus, +}; const FILE_NAME: &str = "control-v1.jsonl"; const MAX_BYTES: usize = 8 * 1024 * 1024; @@ -119,6 +131,18 @@ pub enum ControlError { /// The requested package cache root is invalid or overlaps protected data. #[error("package cache root refused: {0}")] PackageCacheRefused(&'static str), + /// No recorded provider profile has this name. + #[error("provider profile is not recorded")] + UnknownProvider, + /// The requested provider profile is invalid. + #[error("provider profile refused: {0}")] + ProviderRefused(&'static str), + /// No retained approval has this identifier. + #[error("approval is not recorded")] + UnknownApproval, + /// The approval request, decision, or consumption is not valid. + #[error("approval refused: {0}")] + ApprovalRefused(&'static str), } impl From for ControlError { @@ -180,6 +204,11 @@ pub struct ControlSnapshot { /// application storage and the development root. #[serde(skip_serializing_if = "Vec::is_empty")] package_cache_roots: Vec, + #[serde(skip_serializing_if = "Vec::is_empty")] + provider_profiles: Vec, + /// Trusted per-call approval records. Operational state, not settings. + #[serde(skip)] + approvals: Vec, /// Container revocations requested per workspace since the journal was /// created. Derived on replay and never serialized; run watchers compare /// it with the count when their run started. @@ -309,6 +338,22 @@ enum Action { #[serde(deserialize_with = "deserialize_workspace_id")] workspace_id: WorkspaceId, }, + ProviderProfileAdded { + profile: ProviderProfile, + }, + ProviderProfileRemoved { + profile_id: Uuid, + }, + ApprovalRequested { + request: ApprovalRequest, + }, + ApprovalDecided { + approval_id: Uuid, + decision: ApprovalDecision, + }, + ApprovalConsumed { + approval_id: Uuid, + }, } /// One persisted settings/audit event, never prompts or dedicated credential fields. @@ -476,6 +521,8 @@ impl ControlStore { profiles: Vec::new(), package_profiles: Vec::new(), package_cache_roots: Vec::new(), + provider_profiles: Vec::new(), + approvals: Vec::new(), grant_revocations: BTreeMap::new(), }, entries: Vec::new(), @@ -967,6 +1014,9 @@ impl ControlStore { | Action::ContainerGrantRevoked { .. } | Action::PackageFetchStarted { .. } | Action::PackageFetchFinished { .. } + | Action::ApprovalRequested { .. } + | Action::ApprovalDecided { .. } + | Action::ApprovalConsumed { .. } ); let revision = if configuration_change { state @@ -1096,6 +1146,14 @@ impl ControlStore { ))?; state.package_cache_roots.remove(index); } + Action::ProviderProfileAdded { .. } | Action::ProviderProfileRemoved { .. } => { + provider::apply(state, &entry.action, revision)?; + } + Action::ApprovalRequested { .. } + | Action::ApprovalDecided { .. } + | Action::ApprovalConsumed { .. } => { + approval::apply(state, &entry.action, revision)?; + } } state.revision = revision; Ok(()) diff --git a/crates/omgcode-core/src/control/approval.rs b/crates/omgcode-core/src/control/approval.rs new file mode 100644 index 0000000..7a2b6ca --- /dev/null +++ b/crates/omgcode-core/src/control/approval.rs @@ -0,0 +1,449 @@ +//! Trusted per-call approval records. +//! +//! An approval binds a future model-tool call to a session, workspace, +//! operation, exact request digest, and the settings revision in force when it +//! was requested. It stores no argument text. It is single-use and expires. +//! No model tool consumes one yet; the core consume method is the gate a later +//! tool must call. See `docs/agent-instructions.md` and ADR-0039. + +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde::{Deserialize, Serialize}; +use uuid::Uuid; + +use super::{Action, ControlError, ControlSnapshot, ControlStore, valid_uuid}; +use crate::policy::WorkspaceId; + +/// Most approval records retained in one journal. +pub const MAX_APPROVALS: usize = 256; +/// Most undecided approvals at once. +pub const MAX_PENDING_APPROVALS: usize = 64; +/// Shortest accepted approval lifetime. +pub const MIN_APPROVAL_TTL_SECS: u64 = 60; +/// Longest accepted approval lifetime. +pub const MAX_APPROVAL_TTL_SECS: u64 = 60 * 60; +/// Longest approval summary, in bytes. +pub const MAX_APPROVAL_SUMMARY_BYTES: usize = 256; + +/// The model-tool operation an approval covers. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ApprovalOperation { + /// Start a confined command. + Command, + /// Replace or create a workspace file. + FileWrite, + /// Perform a Git operation with remote access. + GitPush, + /// Use a destination-scoped network operation. + Network, +} + +impl ApprovalOperation { + /// The stored spelling. + pub const fn as_str(self) -> &'static str { + match self { + Self::Command => "command", + Self::FileWrite => "file_write", + Self::GitPush => "git_push", + Self::Network => "network", + } + } + + /// Parse a stored or command-line spelling, case-insensitively. + pub fn parse(text: &str) -> Option { + match text.to_ascii_lowercase().as_str() { + "command" => Some(Self::Command), + "file_write" | "file-write" => Some(Self::FileWrite), + "git_push" | "git-push" => Some(Self::GitPush), + "network" => Some(Self::Network), + _ => None, + } + } +} + +/// The operator's decision. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ApprovalDecision { + Approved, + Denied, +} + +/// The current state of one approval, computed with the current time. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ApprovalState { + Pending, + Approved, + Denied, + Consumed, + Expired, +} + +/// A requested approval, before a decision. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct ApprovalRequest { + id: Uuid, + session_id: Uuid, + #[serde(deserialize_with = "super::deserialize_workspace_id")] + workspace_id: WorkspaceId, + operation: ApprovalOperation, + request_sha256: String, + summary: String, + settings_revision: u64, + created_unix: u64, + expires_unix: u64, +} + +/// An internal approval record: the request plus its decision and use. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq)] +pub(super) struct ApprovalRecord { + request: ApprovalRequest, + decision: Option, + consumed: bool, +} + +/// An operator-facing approval view. +#[derive(Clone, Debug, Serialize)] +pub struct ApprovalStatus { + pub id: Uuid, + pub session_id: Uuid, + pub workspace_id: WorkspaceId, + pub operation: ApprovalOperation, + pub request_sha256: String, + pub summary: String, + pub settings_revision: u64, + pub created_unix: u64, + pub expires_unix: u64, + pub state: ApprovalState, +} + +/// An operator's approval request, before validation. +#[derive(Clone, Debug)] +pub struct ApprovalDeclaration { + pub session_id: Uuid, + pub workspace_id: WorkspaceId, + pub operation: ApprovalOperation, + pub request_sha256: String, + pub summary: String, + pub ttl_secs: u64, +} + +/// The exact request a consumer must match. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct ApprovalBinding { + pub session_id: Uuid, + pub workspace_id: WorkspaceId, + pub operation: ApprovalOperation, + pub request_sha256: String, +} + +/// The current Unix time in seconds. +pub fn now_unix() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_secs() +} + +impl ControlStore { + /// Record a pending approval. This preserves the settings revision. + pub fn request_approval( + &mut self, + declaration: &ApprovalDeclaration, + now_unix: u64, + ) -> Result { + if !valid_uuid(declaration.session_id) { + return Err(ControlError::ApprovalRefused( + "the session identifier must be a version 4 UUID", + )); + } + if self.workspace(declaration.workspace_id).is_none() { + return Err(ControlError::UnknownWorkspace); + } + if !valid_digest(&declaration.request_sha256) { + return Err(ControlError::ApprovalRefused( + "the request digest must be 64 lowercase hexadecimal characters", + )); + } + if declaration.summary.is_empty() + || declaration.summary.len() > MAX_APPROVAL_SUMMARY_BYTES + || declaration.summary.contains('\0') + || declaration.summary.chars().any(char::is_control) + { + return Err(ControlError::ApprovalRefused( + "the summary must be 1 to 256 bytes without NUL or control characters", + )); + } + if !(MIN_APPROVAL_TTL_SECS..=MAX_APPROVAL_TTL_SECS).contains(&declaration.ttl_secs) { + return Err(ControlError::ApprovalRefused( + "the approval lifetime must be 60 to 3600 seconds", + )); + } + if self.snapshot.approvals.len() >= MAX_APPROVALS { + return Err(ControlError::ApprovalRefused( + "too many approval records are retained", + )); + } + if self + .snapshot + .approvals + .iter() + .filter(|record| record.decision.is_none()) + .count() + >= MAX_PENDING_APPROVALS + { + return Err(ControlError::ApprovalRefused( + "too many undecided approvals are pending", + )); + } + let request = ApprovalRequest { + id: Uuid::new_v4(), + session_id: declaration.session_id, + workspace_id: declaration.workspace_id, + operation: declaration.operation, + request_sha256: declaration.request_sha256.clone(), + summary: declaration.summary.clone(), + settings_revision: self.revision(), + created_unix: now_unix, + expires_unix: now_unix.saturating_add(declaration.ttl_secs), + }; + validate_request(&request)?; + self.append( + Action::ApprovalRequested { + request: request.clone(), + }, + self.revision(), + )?; + Ok(status_for( + &ApprovalRecord { + request, + decision: None, + consumed: false, + }, + now_unix, + )) + } + + /// Approve or deny one pending approval. This preserves the settings + /// revision. + pub fn decide_approval( + &mut self, + approval_id: Uuid, + approved: bool, + now_unix: u64, + ) -> Result<(), ControlError> { + let record = self + .approval_record(approval_id) + .ok_or(ControlError::UnknownApproval)?; + if record.decision.is_some() { + return Err(ControlError::ApprovalRefused( + "this approval already has a decision", + )); + } + if record.request.expires_unix <= now_unix { + return Err(ControlError::ApprovalRefused("this approval has expired")); + } + self.append( + Action::ApprovalDecided { + approval_id, + decision: if approved { + ApprovalDecision::Approved + } else { + ApprovalDecision::Denied + }, + }, + self.revision(), + ) + } + + /// Consume an approved request once, after checking its exact binding and + /// that the settings revision has not changed. A future model tool must + /// call this before the operation. This preserves the settings revision. + pub fn consume_approval( + &mut self, + approval_id: Uuid, + binding: &ApprovalBinding, + now_unix: u64, + ) -> Result<(), ControlError> { + let record = self + .approval_record(approval_id) + .ok_or(ControlError::UnknownApproval)?; + if record.decision != Some(ApprovalDecision::Approved) { + return Err(ControlError::ApprovalRefused( + "the approval was not granted", + )); + } + if record.consumed { + return Err(ControlError::ApprovalRefused( + "the approval was already consumed", + )); + } + if record.request.expires_unix <= now_unix { + return Err(ControlError::ApprovalRefused("this approval has expired")); + } + if record.request.session_id != binding.session_id + || record.request.workspace_id != binding.workspace_id + || record.request.operation != binding.operation + || record.request.request_sha256 != binding.request_sha256 + { + return Err(ControlError::ApprovalRefused( + "the request does not match the approval", + )); + } + if record.request.settings_revision != self.revision() { + return Err(ControlError::ApprovalRefused( + "the settings changed after the approval was requested", + )); + } + self.append(Action::ApprovalConsumed { approval_id }, self.revision()) + } + + /// The status of one approval, or `None` when it is unknown. + pub fn approval_status(&self, approval_id: Uuid, now_unix: u64) -> Option { + self.approval_record(approval_id) + .map(|record| status_for(record, now_unix)) + } + + /// Every retained approval, oldest first, with its current state. + pub fn approval_statuses(&self, now_unix: u64) -> Vec { + self.snapshot + .approvals + .iter() + .map(|record| status_for(record, now_unix)) + .collect() + } + + fn approval_record(&self, approval_id: Uuid) -> Option<&ApprovalRecord> { + self.snapshot + .approvals + .iter() + .find(|record| record.request.id == approval_id) + } +} + +/// Validate and apply one approval action during replay or append preflight. +pub(super) fn apply( + state: &mut ControlSnapshot, + action: &Action, + _revision: u64, +) -> Result<(), ControlError> { + match action { + Action::ApprovalRequested { request } => { + validate_request(request) + .map_err(|_| ControlError::Invalid("invalid approval request"))?; + if state.approvals.len() >= MAX_APPROVALS + || state + .approvals + .iter() + .any(|record| record.request.id == request.id) + || !state + .workspaces + .iter() + .any(|workspace| workspace.id == request.workspace_id) + || state + .approvals + .iter() + .filter(|record| record.decision.is_none()) + .count() + >= MAX_PENDING_APPROVALS + { + return Err(ControlError::Invalid( + "invalid, duplicate, or excessive approval request", + )); + } + state.approvals.push(ApprovalRecord { + request: request.clone(), + decision: None, + consumed: false, + }); + } + Action::ApprovalDecided { + approval_id, + decision, + } => { + let record = state + .approvals + .iter_mut() + .find(|record| record.request.id == *approval_id) + .ok_or(ControlError::Invalid("decision for an unknown approval"))?; + if record.decision.is_some() { + return Err(ControlError::Invalid("duplicate approval decision")); + } + record.decision = Some(*decision); + } + Action::ApprovalConsumed { approval_id } => { + let record = state + .approvals + .iter_mut() + .find(|record| record.request.id == *approval_id) + .ok_or(ControlError::Invalid("consumption of an unknown approval"))?; + if record.decision != Some(ApprovalDecision::Approved) || record.consumed { + return Err(ControlError::Invalid( + "consumption requires an unused approved record", + )); + } + record.consumed = true; + } + _ => {} + } + Ok(()) +} + +fn status_for(record: &ApprovalRecord, now_unix: u64) -> ApprovalStatus { + let state = if record.consumed { + ApprovalState::Consumed + } else { + match record.decision { + Some(ApprovalDecision::Denied) => ApprovalState::Denied, + Some(ApprovalDecision::Approved) if record.request.expires_unix <= now_unix => { + ApprovalState::Expired + } + Some(ApprovalDecision::Approved) => ApprovalState::Approved, + None if record.request.expires_unix <= now_unix => ApprovalState::Expired, + None => ApprovalState::Pending, + } + }; + ApprovalStatus { + id: record.request.id, + session_id: record.request.session_id, + workspace_id: record.request.workspace_id, + operation: record.request.operation, + request_sha256: record.request.request_sha256.clone(), + summary: record.request.summary.clone(), + settings_revision: record.request.settings_revision, + created_unix: record.request.created_unix, + expires_unix: record.request.expires_unix, + state, + } +} + +fn validate_request(request: &ApprovalRequest) -> Result<(), ControlError> { + if !valid_uuid(request.id) + || !valid_uuid(request.session_id) + || !valid_digest(&request.request_sha256) + || request.summary.is_empty() + || request.summary.len() > MAX_APPROVAL_SUMMARY_BYTES + || request.summary.contains('\0') + || request.summary.chars().any(char::is_control) + || request.expires_unix <= request.created_unix + || request.expires_unix - request.created_unix > MAX_APPROVAL_TTL_SECS + { + return Err(ControlError::ApprovalRefused( + "the approval request is invalid", + )); + } + Ok(()) +} + +fn valid_digest(value: &str) -> bool { + value.len() == 64 + && value + .bytes() + .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()) +} + +#[cfg(test)] +mod tests; diff --git a/crates/omgcode-core/src/control/approval/tests.rs b/crates/omgcode-core/src/control/approval/tests.rs new file mode 100644 index 0000000..156ee92 --- /dev/null +++ b/crates/omgcode-core/src/control/approval/tests.rs @@ -0,0 +1,230 @@ +use super::*; +use std::fs; + +use crate::control::{ + ApprovalBinding, ApprovalDeclaration, ApprovalOperation, ApprovalState, ControlError, + ControlStore, ProviderProfileDeclaration, +}; +use crate::policy::WorkspaceId; +use uuid::Uuid; + +fn scene() -> ( + tempfile::TempDir, + std::path::PathBuf, + WorkspaceId, + ControlStore, +) { + let directory = tempfile::tempdir().expect("temporary directory"); + let data = directory.path().join("data"); + let root = directory.path().join("dev"); + let workspace = root.join("work"); + fs::create_dir_all(&workspace).expect("workspace"); + let mut store = ControlStore::open(&data).expect("store"); + store + .set_development_root(&root, 0) + .expect("development root"); + let workspace_id = store + .register_workspace(&workspace, store.revision()) + .expect("workspace") + .id(); + (directory, data, workspace_id, store) +} + +const NOW: u64 = 1_000_000; +const DIGEST: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; + +fn declaration(workspace_id: WorkspaceId, session_id: Uuid) -> ApprovalDeclaration { + ApprovalDeclaration { + session_id, + workspace_id, + operation: ApprovalOperation::Command, + request_sha256: DIGEST.into(), + summary: "Run the project build".into(), + ttl_secs: 900, + } +} + +fn binding(workspace_id: WorkspaceId, session_id: Uuid) -> ApprovalBinding { + ApprovalBinding { + session_id, + workspace_id, + operation: ApprovalOperation::Command, + request_sha256: DIGEST.into(), + } +} + +#[test] +fn an_approval_is_requested_decided_consumed_once() { + let (_directory, _data, workspace_id, mut store) = scene(); + let session_id = Uuid::new_v4(); + let revision = store.revision(); + let approval = store + .request_approval(&declaration(workspace_id, session_id), NOW) + .expect("request"); + assert_eq!(approval.state, ApprovalState::Pending); + assert_eq!(approval.created_unix, NOW); + assert_eq!(approval.expires_unix, NOW + 900); + assert_eq!(store.revision(), revision, "a request preserves revision"); + store + .decide_approval(approval.id, true, NOW + 1) + .expect("approve"); + assert_eq!( + store + .approval_status(approval.id, NOW + 2) + .expect("status") + .state, + ApprovalState::Approved + ); + store + .consume_approval(approval.id, &binding(workspace_id, session_id), NOW + 3) + .expect("consume"); + assert_eq!( + store + .approval_status(approval.id, NOW + 4) + .expect("status") + .state, + ApprovalState::Consumed + ); + assert!(matches!( + store.consume_approval(approval.id, &binding(workspace_id, session_id), NOW + 5), + Err(ControlError::ApprovalRefused(_)) + )); +} + +#[test] +fn a_denied_or_expired_approval_cannot_be_consumed() { + let (_directory, _data, workspace_id, mut store) = scene(); + let session_id = Uuid::new_v4(); + let denied = store + .request_approval(&declaration(workspace_id, session_id), NOW) + .expect("request"); + store + .decide_approval(denied.id, false, NOW + 1) + .expect("deny"); + assert_eq!( + store + .approval_status(denied.id, NOW + 2) + .expect("status") + .state, + ApprovalState::Denied + ); + assert!(matches!( + store.consume_approval(denied.id, &binding(workspace_id, session_id), NOW + 3), + Err(ControlError::ApprovalRefused(_)) + )); + + let expired = store + .request_approval( + &ApprovalDeclaration { + ttl_secs: MIN_APPROVAL_TTL_SECS, + ..declaration(workspace_id, session_id) + }, + NOW, + ) + .expect("short request"); + assert_eq!( + store + .approval_status(expired.id, NOW + MIN_APPROVAL_TTL_SECS) + .expect("status") + .state, + ApprovalState::Expired + ); + assert!(matches!( + store.decide_approval(expired.id, true, NOW + MIN_APPROVAL_TTL_SECS), + Err(ControlError::ApprovalRefused(_)) + )); +} + +#[test] +fn binding_and_settings_changes_refuse_consumption() { + let (_directory, _data, workspace_id, mut store) = scene(); + let session_id = Uuid::new_v4(); + let approval = store + .request_approval(&declaration(workspace_id, session_id), NOW) + .expect("request"); + store + .decide_approval(approval.id, true, NOW + 1) + .expect("approve"); + + let mut wrong = binding(workspace_id, session_id); + wrong.operation = ApprovalOperation::FileWrite; + assert!(matches!( + store.consume_approval(approval.id, &wrong, NOW + 2), + Err(ControlError::ApprovalRefused(_)) + )); + let mut wrong = binding(workspace_id, session_id); + wrong.request_sha256 = "b".repeat(64); + assert!(matches!( + store.consume_approval(approval.id, &wrong, NOW + 2), + Err(ControlError::ApprovalRefused(_)) + )); + + // A settings change after approval invalidates the recorded revision. + store + .add_provider_profile( + &ProviderProfileDeclaration { + name: "work".into(), + kind: "openai".into(), + auth: "api_key".into(), + }, + store.revision(), + ) + .expect("settings change"); + assert!(matches!( + store.consume_approval(approval.id, &binding(workspace_id, session_id), NOW + 3), + Err(ControlError::ApprovalRefused(_)) + )); +} + +#[test] +fn approvals_survive_replay_and_refuse_invalid_requests() { + let (_directory, data, workspace_id, mut store) = scene(); + let session_id = Uuid::new_v4(); + let approval = store + .request_approval(&declaration(workspace_id, session_id), NOW) + .expect("request"); + store + .decide_approval(approval.id, true, NOW + 1) + .expect("approve"); + let revision = store.revision(); + drop(store); + + let mut store = ControlStore::open(&data).expect("replay"); + assert_eq!(store.revision(), revision); + assert_eq!( + store + .approval_status(approval.id, NOW + 2) + .expect("status") + .state, + ApprovalState::Approved + ); + assert_eq!(store.approval_statuses(NOW + 2).len(), 1); + + for declaration in [ + ApprovalDeclaration { + request_sha256: "not-a-digest".into(), + ..declaration(workspace_id, session_id) + }, + ApprovalDeclaration { + summary: String::new(), + ..declaration(workspace_id, session_id) + }, + ApprovalDeclaration { + ttl_secs: 1, + ..declaration(workspace_id, session_id) + }, + ] { + assert!(matches!( + store.request_approval(&declaration, NOW), + Err(ControlError::ApprovalRefused(_)) + )); + } + assert!(matches!( + store.request_approval(&declaration(WorkspaceId::fresh(), session_id), NOW), + Err(ControlError::UnknownWorkspace) + )); + assert!(matches!( + store.decide_approval(Uuid::new_v4(), true, NOW), + Err(ControlError::UnknownApproval) + )); +} diff --git a/crates/omgcode-core/src/control/provider.rs b/crates/omgcode-core/src/control/provider.rs new file mode 100644 index 0000000..c87e833 --- /dev/null +++ b/crates/omgcode-core/src/control/provider.rs @@ -0,0 +1,296 @@ +//! Operator-declared provider connection profiles. +//! +//! A profile records only a name, a provider kind, and an authentication mode. +//! It stores no endpoint, account, token, password, or other credential, and +//! no adapter uses it yet. It is configuration only. See +//! `docs/provider-authentication.md` and ADR-0038. + +use serde::{Deserialize, Serialize}; +use uuid::Uuid; + +use super::{Action, ControlError, ControlSnapshot, ControlStore, valid_profile_name, valid_uuid}; + +/// Most recorded provider profiles. +pub const MAX_PROVIDER_PROFILES: usize = 32; + +/// A provider that a profile may name. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub enum ProviderKind { + #[serde(rename = "openai")] + OpenAi, + #[serde(rename = "anthropic")] + Anthropic, + #[serde(rename = "ollama_local")] + OllamaLocal, + #[serde(rename = "ollama_cloud")] + OllamaCloud, + #[serde(rename = "open_router")] + OpenRouter, + #[serde(rename = "lm_studio")] + LmStudio, +} + +impl ProviderKind { + /// The stored spelling. + pub const fn as_str(self) -> &'static str { + match self { + Self::OpenAi => "openai", + Self::Anthropic => "anthropic", + Self::OllamaLocal => "ollama_local", + Self::OllamaCloud => "ollama_cloud", + Self::OpenRouter => "open_router", + Self::LmStudio => "lm_studio", + } + } + + /// Parse a stored or command-line spelling, case-insensitively. + pub fn parse(text: &str) -> Option { + match text.to_ascii_lowercase().as_str() { + "openai" => Some(Self::OpenAi), + "anthropic" => Some(Self::Anthropic), + "ollama_local" => Some(Self::OllamaLocal), + "ollama_cloud" => Some(Self::OllamaCloud), + "open_router" => Some(Self::OpenRouter), + "lm_studio" => Some(Self::LmStudio), + _ => None, + } + } +} + +/// How a provider connection would authenticate, when implemented. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ProviderAuth { + /// A provider-supported subscription sign-in. + Subscription, + /// A separately billed API key. + ApiKey, + /// No provider credential; a local or unauthenticated endpoint. + None, +} + +impl ProviderAuth { + /// The stored spelling. + pub const fn as_str(self) -> &'static str { + match self { + Self::Subscription => "subscription", + Self::ApiKey => "api_key", + Self::None => "none", + } + } + + /// Parse a stored or command-line spelling, case-insensitively. + pub fn parse(text: &str) -> Option { + match text.to_ascii_lowercase().as_str() { + "subscription" => Some(Self::Subscription), + "api_key" | "api-key" => Some(Self::ApiKey), + "none" => Some(Self::None), + _ => None, + } + } +} + +/// One recorded provider connection shape. Credentials are never stored here. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +#[serde(deny_unknown_fields)] +pub struct ProviderProfile { + id: Uuid, + name: String, + kind: ProviderKind, + auth: ProviderAuth, +} + +impl ProviderProfile { + /// Stable profile identifier. + pub const fn id(&self) -> Uuid { + self.id + } + + /// The operator's name for the profile. + pub fn name(&self) -> &str { + &self.name + } + + /// The provider kind. + pub const fn kind(&self) -> ProviderKind { + self.kind + } + + /// The authentication mode. + pub const fn auth(&self) -> ProviderAuth { + self.auth + } +} + +/// A profile and the settings revision that recorded it. +#[derive(Clone, Debug, Serialize)] +pub struct ProviderProfileStatus { + #[serde(flatten)] + profile: ProviderProfile, + revision: u64, +} + +impl ProviderProfileStatus { + /// The recorded profile. + pub const fn profile(&self) -> &ProviderProfile { + &self.profile + } + + /// The settings revision of the event that added it. + pub const fn revision(&self) -> u64 { + self.revision + } +} + +/// An operator's provider profile declaration, before parsing. +#[derive(Clone, Debug, Default)] +pub struct ProviderProfileDeclaration { + /// The profile name, with the same rules as other profile names. + pub name: String, + /// A provider spelling such as `openai` or `ollama_local`. + pub kind: String, + /// `subscription`, `api_key`, or `none`. + pub auth: String, +} + +impl ControlStore { + /// Every recorded provider profile, in the order they were added. + pub fn provider_profiles(&self) -> &[ProviderProfileStatus] { + &self.snapshot.provider_profiles + } + + /// The profile with this name, compared case-insensitively. + pub fn provider_profile(&self, name: &str) -> Option<&ProviderProfileStatus> { + self.snapshot + .provider_profiles + .iter() + .find(|status| status.profile.name.eq_ignore_ascii_case(name)) + } + + /// Record a provider connection shape. This advances the settings revision + /// and records no credential or runtime authority. + pub fn add_provider_profile( + &mut self, + declaration: &ProviderProfileDeclaration, + expected_revision: u64, + ) -> Result { + self.check_revision(expected_revision)?; + if self.provider_profiles().len() >= MAX_PROVIDER_PROFILES { + return Err(ControlError::ProviderRefused( + "at most 32 provider profiles may be recorded", + )); + } + if self.provider_profile(&declaration.name).is_some() { + return Err(ControlError::ProviderRefused( + "a provider profile with this name already exists; remove it first", + )); + } + let kind = ProviderKind::parse(&declaration.kind) + .ok_or(ControlError::ProviderRefused("unknown provider kind"))?; + let auth = ProviderAuth::parse(&declaration.auth).ok_or(ControlError::ProviderRefused( + "authentication must be subscription, api_key, or none", + ))?; + let profile = ProviderProfile { + id: Uuid::new_v4(), + name: declaration.name.clone(), + kind, + auth, + }; + validate_profile(&profile)?; + self.append( + Action::ProviderProfileAdded { + profile: profile.clone(), + }, + self.next_revision()?, + )?; + Ok(profile) + } + + /// Remove a provider profile by name. This advances the settings revision. + pub fn remove_provider_profile( + &mut self, + name: &str, + expected_revision: u64, + ) -> Result { + self.check_revision(expected_revision)?; + let profile_id = self + .provider_profile(name) + .ok_or(ControlError::UnknownProvider)? + .profile + .id; + self.append( + Action::ProviderProfileRemoved { profile_id }, + self.next_revision()?, + )?; + Ok(profile_id) + } +} + +/// Validate and apply one provider action during replay or append preflight. +pub(super) fn apply( + state: &mut ControlSnapshot, + action: &Action, + revision: u64, +) -> Result<(), ControlError> { + match action { + Action::ProviderProfileAdded { profile } => { + validate_profile(profile) + .map_err(|_| ControlError::Invalid("invalid provider profile"))?; + if state.provider_profiles.len() >= MAX_PROVIDER_PROFILES + || state.provider_profiles.iter().any(|status| { + status.profile.id == profile.id + || status.profile.name.eq_ignore_ascii_case(&profile.name) + }) + { + return Err(ControlError::Invalid( + "duplicate provider profile or too many provider profiles", + )); + } + state.provider_profiles.push(ProviderProfileStatus { + profile: profile.clone(), + revision, + }); + } + Action::ProviderProfileRemoved { profile_id } => { + let index = state + .provider_profiles + .iter() + .position(|status| status.profile.id == *profile_id) + .ok_or(ControlError::Invalid( + "removal of an unknown provider profile", + ))?; + state.provider_profiles.remove(index); + } + _ => {} + } + Ok(()) +} + +/// Check a profile name and the provider/authentication pairing. +fn validate_profile(profile: &ProviderProfile) -> Result<(), ControlError> { + if !valid_uuid(profile.id) || !valid_profile_name(&profile.name) { + return Err(ControlError::ProviderRefused( + "provider profile names are 1 to 64 ASCII letters, digits, '.', '-', or '_', starting with a letter or digit", + )); + } + if !auth_allowed(profile.kind, profile.auth) { + return Err(ControlError::ProviderRefused( + "this provider does not support the selected authentication mode", + )); + } + Ok(()) +} + +fn auth_allowed(kind: ProviderKind, auth: ProviderAuth) -> bool { + match kind { + ProviderKind::OpenAi | ProviderKind::Anthropic => { + matches!(auth, ProviderAuth::Subscription | ProviderAuth::ApiKey) + } + ProviderKind::OllamaCloud | ProviderKind::OpenRouter => auth == ProviderAuth::ApiKey, + ProviderKind::OllamaLocal => auth == ProviderAuth::None, + ProviderKind::LmStudio => matches!(auth, ProviderAuth::None | ProviderAuth::ApiKey), + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/omgcode-core/src/control/provider/tests.rs b/crates/omgcode-core/src/control/provider/tests.rs new file mode 100644 index 0000000..54018cf --- /dev/null +++ b/crates/omgcode-core/src/control/provider/tests.rs @@ -0,0 +1,116 @@ +use super::*; +use std::fs; + +use crate::control::{ControlError, ControlStore, FILE_NAME}; + +fn store() -> (tempfile::TempDir, std::path::PathBuf, ControlStore) { + let directory = tempfile::tempdir().expect("temporary directory"); + let data = directory.path().join("data"); + let store = ControlStore::open(&data).expect("store"); + (directory, data, store) +} + +fn declaration(name: &str, kind: &str, auth: &str) -> ProviderProfileDeclaration { + ProviderProfileDeclaration { + name: name.into(), + kind: kind.into(), + auth: auth.into(), + } +} + +/// Profiles are recorded with revisions, survive replay, and are removed. +#[test] +fn provider_profiles_are_recorded_replayed_and_removed() { + let (_directory, data, mut store) = store(); + let profile = store + .add_provider_profile(&declaration("work", "openai", "subscription"), 0) + .expect("profile"); + assert_eq!(store.revision(), 1); + let status = store.provider_profile("WORK").expect("case-insensitive"); + assert_eq!(status.profile().id(), profile.id()); + assert_eq!(status.profile().kind(), ProviderKind::OpenAi); + assert_eq!(status.profile().auth(), ProviderAuth::Subscription); + assert_eq!(status.revision(), 1); + let encoded = serde_json::to_value(store.snapshot()).expect("snapshot"); + assert_eq!(encoded["provider_profiles"][0]["name"], "work"); + assert_eq!(encoded["provider_profiles"][0]["kind"], "openai"); + assert_eq!(encoded["provider_profiles"][0]["auth"], "subscription"); + drop(store); + + let mut store = ControlStore::open(&data).expect("replay"); + assert_eq!(store.provider_profiles().len(), 1); + assert!(matches!( + store.add_provider_profile(&declaration("WORK", "anthropic", "api_key"), 1), + Err(ControlError::ProviderRefused(_)) + )); + assert_eq!( + store.remove_provider_profile("work", 1).expect("remove"), + profile.id() + ); + assert_eq!(store.revision(), 2); + assert!(store.provider_profiles().is_empty()); + assert!(matches!( + store.remove_provider_profile("work", 2), + Err(ControlError::UnknownProvider) + )); + let encoded = serde_json::to_value(store.snapshot()).expect("snapshot"); + assert!(encoded.get("provider_profiles").is_none()); +} + +/// A provider and authentication pair must be compatible, and a profile +/// cannot be duplicated or use an unknown spelling. +#[test] +fn invalid_provider_profiles_are_refused_without_a_record() { + let (_directory, data, mut store) = store(); + let cases = [ + ("openai", "none"), + ("anthropic", "none"), + ("ollama_local", "api_key"), + ("ollama_cloud", "subscription"), + ("open_router", "subscription"), + ("lm_studio", "subscription"), + ("unknown", "none"), + ("openai", "password"), + ]; + for (kind, auth) in cases { + let result = store.add_provider_profile(&declaration("bad", kind, auth), 0); + assert!( + matches!(result, Err(ControlError::ProviderRefused(_))), + "{kind}/{auth}: {result:?}" + ); + } + assert_eq!(store.revision(), 0); + assert!(store.provider_profiles().is_empty()); + + store + .add_provider_profile(&declaration("work", "openai", "api_key"), 0) + .expect("profile"); + let result = store.add_provider_profile(&declaration("work", "anthropic", "api_key"), 1); + assert!(matches!(result, Err(ControlError::ProviderRefused(_)))); + drop(store); + let text = fs::read_to_string(data.join(FILE_NAME)).expect("journal text"); + assert_eq!(text.matches("provider_profile_added").count(), 1, "{text}"); +} + +/// Local providers use `none`; cloud key providers require an API key. +#[test] +fn provider_authentication_pairs_are_supported() { + let (_directory, _data, mut store) = store(); + for (index, (kind, auth)) in [ + ("openai", "subscription"), + ("anthropic", "api_key"), + ("ollama_local", "none"), + ("ollama_cloud", "api_key"), + ("open_router", "api_key"), + ("lm_studio", "none"), + ("lm_studio", "api_key"), + ] + .into_iter() + .enumerate() + { + let revision = store.revision(); + store + .add_provider_profile(&declaration(&format!("p{index}"), kind, auth), revision) + .unwrap_or_else(|error| panic!("{kind}/{auth}: {error}")); + } +} diff --git a/docs/README.md b/docs/README.md index a0c4356..0d3d896 100644 --- a/docs/README.md +++ b/docs/README.md @@ -90,7 +90,9 @@ Package-network profiles are recorded as configuration only (ADR-0034); no run uses them, and network access remains all-or-nothing. The trusted `packages fetch` command downloads from declared origins into a per-workspace cache. A selected root is exposed read-only on Linux and Windows; Windows -needs a read-execute grant, and Linux falls back to application storage. The +needs a read-execute grant, and Linux falls back to application storage. +Provider profiles record connection shapes, and approval records prepare +per-call model-tool consent; neither enables an adapter or model tool. The limited file broker and the core read/list turn runtime do not provide general model tools. Chat dispatches only the read and list tools, and only for a workspace that enables `model_tools`. A read-only CLI preview compares a workspace file with trusted proposed diff --git a/docs/adr/0038-record-provider-profiles-without-credentials.md b/docs/adr/0038-record-provider-profiles-without-credentials.md new file mode 100644 index 0000000..bc349e7 --- /dev/null +++ b/docs/adr/0038-record-provider-profiles-without-credentials.md @@ -0,0 +1,74 @@ +# 0038: Record provider profiles without credentials + +- Status: Accepted +- Date: 2026-11-14 + +## Context + +The project plans additional providers: OpenAI, Anthropic/Claude, Ollama Local, +Ollama Cloud, OpenRouter, and the existing local LM Studio route. Subscription +and API-key connections must stay separate, and the current CLI has no +operating-system credential service. Provider login and entitlement routes +still need provider-specific decisions. + +A settings surface is needed before adapters, but it must not become a +credential store or a runtime authorization. + +## Decision + +Record operator-declared provider connection shapes: + +```text +omgcode workspace provider-profile-add --kind --auth + --revision +omgcode workspace provider-profile-show +omgcode workspace provider-profile-remove --revision +``` + +- **Contents:** a profile name, a provider kind, and an authentication mode. + It stores no endpoint, account, token, password, certificate, or other + credential. +- **Kinds:** `openai`, `anthropic`, `ollama_local`, `ollama_cloud`, + `open_router`, `lm_studio`. +- **Authentication:** `subscription`, `api_key`, or `none`. Subscription is + accepted only for OpenAI and Anthropic. API keys are accepted for those, + Ollama Cloud, OpenRouter, and LM Studio. Local providers use `none`; + Ollama Local accepts only `none`. +- **Shape:** at most 32 profiles, names follow the existing profile-name rules + and compare case-insensitively. Each change uses the expected settings + revision and records `provider_profile_added` or `provider_profile_removed`. +- **Not runtime:** no adapter, login, entitlement check, billing mode, or + model context uses a profile. `capabilities` reports + `provider_profiles: true` and `provider_adapters: false`. + +A later provider increment must add a reviewed credential service, keep +subscription and API-key usage separate, never silently fall back to paid API +usage, and bind credentials to the provider, account, and endpoint. + +## Alternatives considered + +- **Store tokens or API keys in the profile.** Rejected: the settings journal + is not a credential store, and values are shown by `status`. +- **Store endpoints and accounts now.** Deferred: an endpoint is meaningful + only with an adapter and a credential policy, and it would invite secrets in + the profile. +- **Wait for adapters before adding profiles.** Rejected: the separation of + subscription, API-key, and local modes is a contract worth fixing first. + +## Consequences + +- Operators can prepare connection shapes, but nothing connects or + authenticates. +- A credential service remains a prerequisite for any real provider adapter. +- The control journal gains provider events. A journal written by 0.24.0 + cannot be read by 0.23.0. +- Provider profiles are configuration, not permission. A future adapter must + still check the selected profile, account, entitlement, and billing mode at + call time. + +## References + +- [Provider authentication](../provider-authentication.md) +- [Workspace settings](../workspace-permissions.md) +- [Security coding rules](../security-coding-rules.md#provider-traffic-and-tool-calls) +- [Testing standards](../testing-standards.md) diff --git a/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md b/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md new file mode 100644 index 0000000..9c931b3 --- /dev/null +++ b/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md @@ -0,0 +1,87 @@ +# 0039: Gate future model tools with bound, single-use approval records + +- Status: Accepted +- Date: 2026-11-14 + +## Context + +Model-authorised tools need per-call approval. Prompt text, a model claim, or a +journal record cannot authorize a host action. The current chat is one +non-interactive turn and there is no approval UI. A future tool therefore +needs a trusted, durable decision that binds the exact request and cannot be +reused. + +The [security rules](../security-coding-rules.md) require binding +authorization to a session, workspace, operation, target, policy revision, and +lifetime, and invalidating pending grants when policy changes. + +## Decision + +Record approvals in the bounded control journal and expose trusted CLI +commands: + +```text +omgcode approvals request --session --workspace + --operation + --digest --summary [--ttl-secs <60-3600>] +omgcode approvals list +omgcode approvals show +omgcode approvals approve +omgcode approvals deny +omgcode approvals consume --session --workspace + --operation --digest +``` + +Rules: + +- **Binding:** a request records its session, workspace, operation, exact + request SHA-256, settings revision, creation time, and expiry. It stores no + argument text. The summary is limited to 256 bytes, must be non-empty, and + must contain no NUL or control characters; it must never contain secrets. +- **Lifetime:** 60 to 3600 seconds. An expired pending or approved request + cannot be decided or consumed. +- **Single use:** an approved request is consumed once. Consumption checks the + session, workspace, operation, digest, and that the settings revision is + still the one recorded at request time. Any settings change invalidates the + approval. +- **Revision:** approval events preserve the settings revision. A request + requires an existing registered workspace; the CLI request command is a + trusted operator action. +- **No execution:** the CLI consume command only marks the record used. No + model tool executes in this phase. A future tool must call the core + consumption check immediately before its operation and must fail closed if + the approval is missing, denied, expired, consumed, or bound differently. +- **Limits:** at most 256 retained approval records and 64 undecided ones. + Retention is not compaction; a full journal refuses new requests. + +## Alternatives considered + +- **Prompt-only consent or a model claim of consent.** Rejected: prompt text + grants nothing. +- **A session-wide or workspace-wide allowlist.** Rejected: it authorizes more + than one call and cannot bind the exact request. +- **A separate approvals journal.** Deferred: the control journal already + provides durable single-writer authorization state with a settings + revision, and approvals preserve that revision. +- **Automatic approval after a timeout.** Rejected: silence is not consent. + +## Consequences + +- A future model tool has a real per-call gate to call. No model tool, UI, or + execution path exists yet. +- The operator uses CLI commands until an approval UI exists. The CLI request + command is a testing and manual-flow surface; a model tool would create the + request through the same core method. +- A settings change between approval and consumption invalidates the approval, + even when the change is unrelated. This is conservative and visible. +- Retained approval records consume control-journal capacity. Archiving or + compaction is a separate concern. +- A journal written by 0.24.0 cannot be read by 0.23.0. + +## References + +- [Agent instructions](../agent-instructions.md) +- [Workspace settings](../workspace-permissions.md) +- [Security coding rules](../security-coding-rules.md) +- [Testing standards](../testing-standards.md) +- [ADR-0038](0038-record-provider-profiles-without-credentials.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 132dcf8..c6a5f29 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -52,3 +52,5 @@ meaningful alternative does not need an ADR. | [0035: Fetch packages through a trusted allowlisted cache](0035-fetch-packages-through-a-trusted-allowlisted-cache.md) | Accepted | 2026-11-13 | | [0036: Expose the package fetch cache read-only to Linux runs](0036-expose-the-package-fetch-cache-read-only-to-linux-runs.md) | Superseded by ADR-0037 | 2026-11-14 | | [0037: Use a per-workspace cache root and a scoped Windows grant](0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md) | Accepted | 2026-11-14 | +| [0038: Record provider profiles without credentials](0038-record-provider-profiles-without-credentials.md) | Accepted | 2026-11-14 | +| [0039: Gate future model tools with bound, single-use approval records](0039-gate-future-model-tools-with-bound-single-use-approval-records.md) | Accepted | 2026-11-14 | diff --git a/docs/agent-instructions.md b/docs/agent-instructions.md index 11c1555..2d3dd9b 100644 --- a/docs/agent-instructions.md +++ b/docs/agent-instructions.md @@ -156,6 +156,24 @@ Claude Code prompts. [OpenAI request mapping](https://developers.openai.com/api/docs/guides/migrate-to-responses), [Claude Messages](https://platform.claude.com/docs/en/api/messages/create) +## Approval records + +A future model tool that changes host state must obtain a trusted, single-use +approval record. `approvals request` records a pending request; +`approvals list`, `show`, `approve`, and `deny` inspect or decide it; and +`approvals consume` marks an approved record used. The record binds the +session, workspace, operation, exact request SHA-256, and the settings revision +at request time. It stores no argument text. The summary is at most 256 bytes, +must contain no secrets or control characters, and is for the operator. + +An approval lives 60 to 3600 seconds and is consumed at most once. Consumption +checks the binding and refuses if the settings revision changed. The CLI +consume command executes nothing. A future model tool must call the core +consumption check immediately before its operation and fail closed when the +record is missing, denied, expired, consumed, or bound differently. Approval +events preserve the settings revision. See +[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). + ## Release request records Freeze an instruction manifest when starting each request. Record the prompt diff --git a/docs/provider-authentication.md b/docs/provider-authentication.md index 2c6a8bc..412d873 100644 --- a/docs/provider-authentication.md +++ b/docs/provider-authentication.md @@ -127,6 +127,22 @@ before calling this feature available. A CLI or SDK wrapper alone is not evidence of that approval. Keep the requirement open and the blocker visible; a separately billed Anthropic API connection remains a different profile. +## Recorded provider profiles (0.24.0) + +`workspace provider-profile-add/show/remove` record a name, a provider kind, +and an authentication mode. Kinds are `openai`, `anthropic`, `ollama_local`, +`ollama_cloud`, `open_router`, and `lm_studio`; modes are `subscription`, +`api_key`, and `none`. Subscription is accepted only for OpenAI and Anthropic. +API keys are accepted for those, Ollama Cloud, OpenRouter, and LM Studio. +Ollama Local accepts only `none`. + +A profile stores no endpoint, account, token, password, certificate, or other +credential. It is configuration only: no adapter, login, entitlement check, +billing mode, or model context uses it. `capabilities` reports +`provider_profiles: true` and `provider_adapters: false`. A credential service +and the provider-specific login approvals remain prerequisites for any real +connection. See [ADR-0038](adr/0038-record-provider-profiles-without-credentials.md). + ## Settings and account lifecycle ### LM Studio release connection requirements diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index f82b479..7b5c916 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -225,6 +225,16 @@ crate. when a destination or redirect changes. Enabling a destination also permits some data to reach it; do not describe a destination allowlist as content confidentiality. +- Provider profiles record only a name, kind, and authentication mode. Never + store a token, password, certificate, endpoint, or account in them. Keep + subscription and API-key usage separate, and do not implement an adapter or + login without a reviewed credential service and the provider's supported + route. A profile is configuration, not authentication. See ADR-0038. +- A future model tool that changes host state must consume a trusted, + single-use approval bound to the session, workspace, operation, exact + request digest, and settings revision. Refuse a missing, denied, expired, + consumed, mismatched, or settings-invalidated record. Prompt text, model + claims, and recorded intents never grant authority. See ADR-0039. - Do not enforce a package or task destination list with proxy environment variables or an advisory loopback proxy: a confined tree can ignore them and connect directly. A package-network profile is configuration only until a diff --git a/docs/testing-standards.md b/docs/testing-standards.md index aeebfae..7d13804 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -145,6 +145,8 @@ As the relevant components are implemented, include: | Networking | Disabled egress, host-local access, redirects, provider routing | | Package network | Profile storage and the trusted fetch: recording, replay, revision, origin normalization, duplicate and invalid-origin refusal, removal, task-network gating, undeclared-origin and path refusal before a request, redirect refusal, size limits, cache-name validation, existing-cache refusal, private cache content, and start/finish audit without the URL text. Cache roots cover per-workspace set/clear/replay, overlap refusals, the configured fetch location, Linux read/write/parent denial, Windows access with a scoped grant, and Windows refusal without one. No run accepts a profile. A future run-side mechanism must add allowed-origin success, undeclared-origin refusal, redirect and credential refusal, offline fallback, and platform refusal ([ADR-0034](adr/0034-gate-package-networking-behind-enforceable-destination-control.md), [ADR-0035](adr/0035-fetch-packages-through-a-trusted-allowlisted-cache.md), [ADR-0037](adr/0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md)) | | Providers | Partial/malformed streams, duplicate calls, interruption, retries | +| Provider profiles | Kind/authentication pairing, duplicate and invalid names, case-insensitive lookup, revisioned add/remove, replay, no credential or endpoint storage, and capability reporting. No adapter or login is exercised | +| Approvals | Request validation, pending/list/show, approve/deny, single-use consume, expiry, binding mismatch, settings-revision invalidation, replay, unknown IDs, and limits. No operation executes | | Authentication | Callback binding, consent, subscription entitlement, refresh, revocation, account/billing isolation | | Toolchains | Native compiler/SDK dependencies, interpreters, formatter/build/test flows, caches, helper processes, denied host access | | Git | Hostile config/hooks/helpers, metadata paths, changed push approvals | diff --git a/docs/workspace-permissions.md b/docs/workspace-permissions.md index 4910933..26a044e 100644 --- a/docs/workspace-permissions.md +++ b/docs/workspace-permissions.md @@ -122,6 +122,11 @@ zero-based sequence, UTC timestamp, global revision, and tagged `action`: | `package_fetch_finished` | Trusted package-fetch outcome; preserve revision | | `package_cache_root_set` | Select one workspace's package cache root; increment revision | | `package_cache_root_cleared` | Clear one workspace's package cache root; increment revision | +| `provider_profile_added` | New provider profile; increment revision | +| `provider_profile_removed` | Remove a provider profile; increment revision | +| `approval_requested` | Trusted approval request; preserve revision | +| `approval_decided` | Approval granted or denied; preserve revision | +| `approval_consumed` | Approval used once; preserve revision | Operational file checks do not append `policy_checked`. They use current settings and their separate [operation journal](file-access.md). This prevents @@ -211,6 +216,32 @@ written by 0.23.0 cannot be read by 0.22.0. The [execution guide](execution.md#trusted-package-fetch) owns the fetch, exposure, and grant rules. +## Provider profiles + +`workspace provider-profile-add --kind --auth +--revision `, `provider-profile-show `, and +`provider-profile-remove --revision ` record provider connection +shapes. They store no credential, endpoint, or account. Adding and removing +use the expected revision and increment it through `provider_profile_added` +and `provider_profile_removed`; `workspace status` lists them under +`provider_profiles` and omits the field until one exists. The +[provider authentication guide](provider-authentication.md) owns the kind and +authentication matrix. A control journal written by 0.24.0 cannot be read by +0.23.0. + +## Approval records + +`approvals request`, `list`, `show`, `approve`, `deny`, and `consume` manage +trusted per-call approvals. A request records a session, workspace, operation, +exact request digest, summary, settings revision, and expiry. The events +`approval_requested`, `approval_decided`, and `approval_consumed` preserve the +settings revision. A decision or consumption is refused after expiry, +mismatch, reuse, or any settings change. No model tool consumes an approval +yet, and the CLI consume command executes nothing. The +[agent instructions guide](agent-instructions.md#approval-records) owns the +tool-side contract. See +[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). + ## Task network `workspace permissions --revision --task-network true` lets a From f400108d905cab9a3f4578834495ac5fda945bac Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 10:46:41 +0000 Subject: [PATCH 09/17] feat: add an approval-gated model command tool Add workspace_run_command to the turn runtime. It is advertised only under live model_tools, execute, read, and write. A first call records a pending approval and starts nothing; an identical call after approval consumes the bound record and runs through the trusted runner with fixed limits, no shell, and no network or host services. The gate and run hand-off are tested; a successful native command on both hosts remains a separate qualification. Version 0.25.0. See ADR-0040. Co-Authored-By: Claude Code --- AGENTS.md | 7 +- CHANGELOG.md | 18 + Cargo.lock | 6 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 28 +- README.md | 29 +- crates/omgcode-cli/src/main.rs | 2 + crates/omgcode-cli/tests/control_workflow.rs | 2 + crates/omgcode-core/src/turn.rs | 487 +++++++++++++++++- crates/omgcode-core/tests/turn_runtime.rs | 226 +++++++- docs/README.md | 3 +- ...st-tools-through-a-workspace-preference.md | 2 +- ...nds-through-recorded-toolchain-profiles.md | 3 +- ...-with-bound-single-use-approval-records.md | 4 +- ...l-with-approvals-and-the-trusted-runner.md | 96 ++++ docs/adr/index.md | 1 + docs/agent-instructions.md | 34 +- docs/development-tools.md | 4 +- docs/development.md | 28 +- docs/execution.md | 52 +- docs/file-access.md | 2 +- docs/platform-support.md | 2 +- docs/security-coding-rules.md | 6 + docs/testing-standards.md | 1 + docs/workspace-permissions.md | 21 +- 25 files changed, 975 insertions(+), 91 deletions(-) create mode 100644 docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md diff --git a/AGENTS.md b/AGENTS.md index 6d48457..2bcc78c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,9 +8,12 @@ preferences, a bounded native file broker exposed through trusted CLI commands, and native identity checks. Follow [workspace settings](docs/workspace-permissions.md) and [workspace file access](docs/file-access.md) for their contracts. Enabled preferences never authorize execution. The prototype is not a desktop app. -Chat offers the local LM Studio model only read and list tools, and only for a +Chat offers the local LM Studio model read and list tools, and, when the +workspace also enables `execute`, `read`, and `write`, one command tool that +requires a trusted single-use approval. No model write, network, Git, or MCP +tool exists. Chat offers tools only for a workspace whose `model_tools` preference is enabled. There are no model write -tools, other provider adapters, or model-callable process execution. The +tools, other provider adapters, or unreviewed model-callable process execution. The trusted CLI `run` command starts one program for a workspace whose `execute` preference is enabled. It uses an operator-declared toolchain profile, records intent and outcome in a run journal, and applies Landlock and a seccomp socket diff --git a/CHANGELOG.md b/CHANGELOG.md index 9922a03..9cfeaf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,24 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.25.0 adds an approval-gated model command tool. See ADR-0040. + - **Offering:** `workspace_run_command` is advertised only when the + workspace's live `model_tools`, `execute`, `read`, and `write` + preferences are enabled. Every call rechecks them; the trusted run checks + them again. + - **Arguments:** a recorded toolchain profile, program, at most 64 + arguments, and an optional workspace-relative `cwd`. There is no shell. + - **Approval:** the first call records a pending approval and returns + `approval_required`; it starts nothing. After `approvals approve `, a + second identical call consumes the approval and calls the trusted runner. + The model cannot approve, select limits, or select network/host services. + - **Limits:** 20-second deadline, 32 KiB per output stream, 1 GiB memory, + 64 processes, 20 seconds of CPU, and 256 MiB of disk growth. + - **Records:** the session journal records the tool intent/result; the run + journal records the run. A failed run consumes the approval; no replay + executes a recorded call. + - **Not qualified:** a successful native command on both hosts as a + model-tool acceptance case; the gate and run hand-off are tested. - Version 0.24.0 records provider profiles and trusted per-call approvals. See ADR-0038 and ADR-0039. - **Provider profiles:** `workspace provider-profile-add/show/remove` record diff --git a/Cargo.lock b/Cargo.lock index c9b01e8..77c9829 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -672,7 +672,7 @@ checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" [[package]] name = "omgcode-cli" -version = "0.24.0" +version = "0.25.0" dependencies = [ "clap", "directories", @@ -685,7 +685,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.24.0" +version = "0.25.0" dependencies = [ "libc", "omgcode-platform", @@ -701,7 +701,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.24.0" +version = "0.25.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index 95d1c27..22f94ff 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform"] [workspace.package] -version = "0.24.0" +version = "0.25.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index f164761..af9a4d7 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -65,11 +65,13 @@ This is a resume guide, not a replacement for the owning contracts in the trusted allowlisted package fetch and private cache (ADR-0035), and **Phase C11**, version **0.22.0**, with read-only Linux run access to that cache (ADR-0036), **Phase C12**, version **0.23.0**, with per-workspace - cache roots and scoped Windows access (ADR-0037), and **Phase C13**, version + cache roots and scoped Windows access (ADR-0037), **Phase C13**, version **0.24.0**, with provider-profile records and trusted per-call approvals - (ADR-0038, ADR-0039). It is stacked on C7 at `0426e42`. No run accepts a - profile or has destination-scoped networking; no provider adapter or model - tool is enabled. + (ADR-0038, ADR-0039), and **Phase C14**, version **0.25.0**, with the + approval-gated model command tool (ADR-0040). It is stacked on C7 at + `0426e42`. No run accepts a profile or has destination-scoped networking; + no provider adapter is enabled, and the command tool is the only model tool + that can request a process. Implemented today: @@ -157,6 +159,11 @@ Implemented today: session, workspace, operation, request digest, and settings revision, expire, and are consumed once (ADR-0039). Neither enables a provider connection or a model tool. +- The `workspace_run_command` model tool (ADR-0040) is offered only with live + `model_tools`, `execute`, `read`, and `write`. Its first call records a + pending approval and starts nothing; an approved exact call consumes the + approval and uses the trusted runner with fixed limits. No write, network, + Git, or MCP model tool exists. - Trusted `file restore` through a new checkpoint and `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See @@ -533,15 +540,22 @@ on Windows, and trusted CLI commands as the first caller. See - **C13 (this branch, version 0.24.0):** provider-profile records and trusted per-call approval records. Profiles store only a name, kind, and authentication mode; no credential, endpoint, adapter, or login exists. - Approvals are bound, expiring, single-use records; no model tool consumes - one yet. See + Approvals are bound, expiring, single-use records; the first consumer is the + command tool in C14. See [ADR-0038](docs/adr/0038-record-provider-profiles-without-credentials.md) and [ADR-0039](docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). +- **C14 (this branch, version 0.25.0):** the `workspace_run_command` model + tool. It is offered only with live model-tools/execute/read/write, records a + pending approval on the first call, and consumes an approved exact record + before calling the trusted runner. It uses fixed limits and no network or + host services. See + [ADR-0040](docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). Next decisions, not yet scheduled: - a credential service, provider adapters, and subscription/API-key login; -- a model-callable command tool that consumes the approval record; +- model write, network, Git, and MCP tools; +- native successful-command qualification for the model tool; - registry credentials and development-server networking. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/README.md b/README.md index a5ebc2f..28cde8c 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,9 @@ OMGCode aims to connect language models to controlled development tools. The current code is an early Rust core and command-line prototype. A bounded native workspace file broker is available through trusted CLI commands. A core turn/tool runtime and schema-v2 session format let chat offer the local LM Studio -model read and list tools, only for a workspace that enables `model_tools`. -Model write and process tools, a desktop interface, and Git workflows remain +model read, list, and approval-gated command tools, only for a workspace that +enables `model_tools` and the command tool's own preferences. +Model write tools, a desktop interface, and Git workflows remain planned. The trusted CLI `run` command starts one program for a workspace whose `execute` preference is enabled. It uses an operator-declared toolchain profile, records each run in a run journal, and confines the process tree with @@ -23,7 +24,10 @@ directory grants. > an explicitly selected local LM Studio model. > When a workspace enables the `model_tools` preference, chat lets the local > model read and list files inside that workspace through a bounded runtime. -> It has no model write, process, network, Git, or MCP tools. The trusted +> When `execute`, `read`, and `write` are also enabled, it offers a confined +> command tool that records a pending approval and runs only after the operator +> approves that exact call. It has no model write, network, Git, or MCP tools. +> The trusted > CLI can replace or restore one existing file through a checkpoint on qualified > Linux ext4 or Windows NTFS, and can permanently delete one resolved checkpoint. > The `file` commands cannot delete workspace files. The trusted CLI `run` @@ -86,8 +90,9 @@ and `omgcode-platform`. The CLI command is `omgcode`. It provides: - `chat`: send one user turn to an already-running LM Studio server at a literal loopback HTTP endpoint. It does not discover, start, or download models, and it rejects model tool requests unless the session's workspace enables - `model_tools`. Then it offers only the read and list tools, rechecked against - live settings before every call. + `model_tools`. Then it offers read/list tools and, when `execute`, `read`, + and `write` are also enabled, the approval-gated command tool, rechecked + against live settings before every call. Prompt assembly sends the compiled base in the system role. Optional user preferences and conversation history remain user or assistant messages. The @@ -98,11 +103,11 @@ marked interrupted before chat can continue. The core also implements a session-owned turn/tool runtime and JSONL schema version 2. That runtime accepts a caller-supplied model interface, validates -strict read/list tool calls, creates a fresh workspace binding before every -operation, and records tool intents, results, and source-labelled messages. -Only bounded read and directory listing are supported. `chat` runs it with the -local LM Studio adapter for a workspace that enables `model_tools`. It has no -write, process, Git, MCP, or network tool. +strict read/list/command tool calls, creates a fresh workspace binding before +every file operation, and records tool intents, results, and source-labelled +messages. The command tool additionally requires a consumed approval. `chat` +runs it with the local LM Studio adapter for a workspace that enables +`model_tools`. It has no write, Git, MCP, or network tool. New sessions use schema version 2; version 1 journals remain readable and writable with their original text-only event subset. @@ -154,7 +159,9 @@ conservative byte-based estimate; it is not the model tokenizer. While the workspace's `model_tools` preference is off, which is the default, the example sends only the supplied message and saved chat history, not workspace files; earlier tool results are replaced by a withheld notice. If `model_tools` is -enabled for `.`, the model can call the read and list tools, and the file +enabled for `.`, the model can call the read and list tools; with `execute`, +`read`, and `write` also enabled it can request the command tool, which needs +an operator approval. The file contents it reads are sent to the local model. The loopback connection does not establish how LM Studio handles data upstream; check the server's configuration before sending sensitive text. diff --git a/crates/omgcode-cli/src/main.rs b/crates/omgcode-cli/src/main.rs index c3ef5f1..9f212b1 100644 --- a/crates/omgcode-cli/src/main.rs +++ b/crates/omgcode-cli/src/main.rs @@ -237,6 +237,8 @@ fn run(cli: Cli) -> Result<(), CliError> { "checkpoint_deletion": cfg!(any(target_os = "linux", target_os = "windows")), "edit_previews": cfg!(any(target_os = "linux", target_os = "windows")), "model_read_list_tools": model_tools::MODEL_TOOLS_SUPPORTED, + "model_command_tool": "approval_required", + "model_write_tools": false, "workspace_container_grants": omgcode_core::control::CONTAINER_GRANTS_SUPPORTED, "workspace_file_tools": false, "toolchain_profiles": RUN_SUPPORTED, diff --git a/crates/omgcode-cli/tests/control_workflow.rs b/crates/omgcode-cli/tests/control_workflow.rs index 9bc72a7..1305aa7 100644 --- a/crates/omgcode-cli/tests/control_workflow.rs +++ b/crates/omgcode-cli/tests/control_workflow.rs @@ -448,6 +448,8 @@ fn capabilities_report_configuration_only_policy_and_trusted_runs_only() { assert_eq!(capabilities["workspace_container_grants"], cfg!(windows)); let runs = cfg!(any(target_os = "linux", windows)); assert_eq!(capabilities["toolchain_profiles"], runs); + assert_eq!(capabilities["model_command_tool"], "approval_required"); + assert_eq!(capabilities["model_write_tools"], false); assert_eq!(capabilities["package_network_profiles"], true); assert_eq!(capabilities["package_network_enforcement"], false); assert_eq!(capabilities["package_fetch"], true); diff --git a/crates/omgcode-core/src/turn.rs b/crates/omgcode-core/src/turn.rs index ee670f7..62a630a 100644 --- a/crates/omgcode-core/src/turn.rs +++ b/crates/omgcode-core/src/turn.rs @@ -7,6 +7,7 @@ //! advertise or dispatch model tools, and no process or network tool exists. use std::collections::HashSet; +use std::ffi::OsString; use std::io; use std::path::{Component, Path, PathBuf}; use std::sync::Arc; @@ -18,9 +19,12 @@ use serde_json::{Value, json}; use thiserror::Error; use uuid::Uuid; -use crate::control::{ControlError, ControlStore}; +use crate::control::{ + ApprovalBinding, ApprovalDeclaration, ApprovalOperation, ApprovalState, ControlError, + ControlStore, now_unix, valid_profile_name, +}; use crate::files::{FileBroker, FileError, FileListing, FileTarget}; -use crate::policy::{DecisionReason, WorkspaceId}; +use crate::policy::{DecisionReason, PermissionSet, WorkspaceId}; use crate::prompt::{ self, BASE_PROMPT, BASE_PROMPT_VERSION, ConversationMessage, ConversationRole, ModelMessage, PromptError, @@ -31,7 +35,7 @@ use crate::session::{ }; /// Revision of the tool schemas advertised by this runtime. -pub const TOOL_SCHEMA_VERSION: &str = "0.1.0"; +pub const TOOL_SCHEMA_VERSION: &str = "0.2.0"; /// Maximum model requests in one turn, including the text-only final request. pub const MAX_TOOL_ROUNDS: usize = 4; @@ -57,6 +61,20 @@ pub const MAX_LIST_ENTRIES: usize = 512; pub const DEFAULT_LIST_ENTRIES: usize = 128; /// Hard upper bound for a caller-selected turn deadline. pub const MAX_TURN_DEADLINE: Duration = Duration::from_secs(300); +/// Most arguments accepted by one model command call. +pub const MAX_COMMAND_ARGUMENTS: usize = 64; +/// Longest one model command argument, in bytes. +pub const MAX_COMMAND_ARGUMENT_BYTES: usize = 1024; +/// Longest total model command arguments, in bytes. +pub const MAX_COMMAND_TOTAL_BYTES: usize = 16 * 1024; +/// Longest model command program, in bytes. +pub const MAX_COMMAND_PROGRAM_BYTES: usize = 1024; +/// Deadline for one model command run. +pub const COMMAND_DEADLINE: Duration = Duration::from_secs(20); +/// Retained bytes from each model command output stream. +pub const COMMAND_OUTPUT_BYTES: usize = 32 * 1024; +/// Approval lifetime requested by a model command call. +pub const COMMAND_APPROVAL_TTL_SECS: u64 = 900; /// A model interface which can return text and raw tool-call values. /// @@ -163,6 +181,43 @@ pub fn tool_definitions() -> Vec { ] } +/// The command tool. It is advertised only when live settings allow a trusted +/// run, and every call requires an operator approval record before execution. +pub fn command_tool_definition() -> ToolDefinition { + ToolDefinition { + name: "workspace_run_command", + description: "Request one confined command under a recorded toolchain \ + profile. The first call records a pending operator approval \ + and does not execute. After the operator approves, call it \ + again with the same arguments. Output is untrusted.", + parameters: json!({ + "type": "object", + "properties": { + "profile": { + "type": "string", + "description": "Recorded toolchain profile name." + }, + "program": { + "type": "string", + "description": "Program path or bare name resolved inside the profile or workspace." + }, + "arguments": { + "type": "array", + "items": {"type": "string"}, + "maxItems": MAX_COMMAND_ARGUMENTS, + "description": "Arguments passed exactly, without a shell." + }, + "cwd": { + "type": "string", + "description": "Workspace-relative working directory; the workspace when omitted." + } + }, + "required": ["profile", "program"], + "additionalProperties": false + }), + } +} + /// A supported tool name. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum ToolName { @@ -170,6 +225,8 @@ pub enum ToolName { ReadFile, /// List one directory. ListDirectory, + /// Request or run one confined command. + Command, } impl ToolName { @@ -178,6 +235,7 @@ impl ToolName { match self { Self::ReadFile => "workspace_read_file", Self::ListDirectory => "workspace_list_directory", + Self::Command => "workspace_run_command", } } } @@ -199,6 +257,17 @@ pub enum ToolArguments { /// Positive entry limit. max_entries: usize, }, + /// Request or run one confined command. + Command { + /// Recorded toolchain profile name. + profile: String, + /// Program path or bare name. + program: String, + /// Exact arguments. + arguments: Vec, + /// Workspace-relative working directory. + cwd: Option, + }, } /// One strictly validated model tool call. @@ -262,6 +331,7 @@ impl ToolCall { let name = match name { "workspace_read_file" => ToolName::ReadFile, "workspace_list_directory" => ToolName::ListDirectory, + "workspace_run_command" => ToolName::Command, _ => return Err(ToolCallError::UnsupportedTool), }; let arguments_json = function @@ -331,6 +401,71 @@ impl ToolCall { max_entries, } } + ToolName::Command => { + let mut profile = None; + let mut program = None; + let mut arguments = Vec::new(); + let mut cwd = None; + for (key, value) in arguments_object { + match key.as_str() { + "profile" => { + profile = Some(value.as_str().ok_or(ToolCallError::InvalidArguments)?); + } + "program" => { + program = Some(value.as_str().ok_or(ToolCallError::InvalidArguments)?); + } + "arguments" => { + let values = value.as_array().ok_or(ToolCallError::InvalidArguments)?; + if values.len() > MAX_COMMAND_ARGUMENTS { + return Err(ToolCallError::InvalidArguments); + } + let mut total = 0usize; + for argument in values { + let argument = + argument.as_str().ok_or(ToolCallError::InvalidArguments)?; + if argument.len() > MAX_COMMAND_ARGUMENT_BYTES + || argument.contains('\0') + { + return Err(ToolCallError::InvalidArguments); + } + total = total + .checked_add(argument.len()) + .filter(|total| *total <= MAX_COMMAND_TOTAL_BYTES) + .ok_or(ToolCallError::InvalidArguments)?; + arguments.push(argument.to_owned()); + } + } + "cwd" => { + cwd = Some(value.as_str().ok_or(ToolCallError::InvalidArguments)?); + } + _ => return Err(ToolCallError::InvalidArguments), + } + } + let profile = profile.ok_or(ToolCallError::InvalidArguments)?; + let program = program.ok_or(ToolCallError::InvalidArguments)?; + if !valid_profile_name(profile) + || program.is_empty() + || program.len() > MAX_COMMAND_PROGRAM_BYTES + || program.contains('\0') + || program.chars().any(char::is_control) + { + return Err(ToolCallError::InvalidArguments); + } + let cwd = match cwd { + Some("") => None, + Some(path) => { + validate_relative_path(path, true)?; + Some(path.to_owned()) + } + None => None, + }; + ToolArguments::Command { + profile: profile.to_owned(), + program: program.to_owned(), + arguments, + cwd, + } + } }; Ok(Self { call_id: call_id.to_owned(), @@ -341,11 +476,15 @@ impl ToolCall { } /// Return the validated workspace-relative path used for dispatch. + /// + /// A command call has no single path; it returns an empty string and the + /// dispatcher uses its typed arguments. pub fn path(&self) -> &str { match &self.arguments { ToolArguments::ReadFile { path, .. } | ToolArguments::ListDirectory { path, .. } => { path } + ToolArguments::Command { .. } => "", } } @@ -697,7 +836,10 @@ impl<'a> TurnRuntime<'a> { .ok_or(TurnError::Timeout)?; self.check_checkpoints(deadline)?; - let tools = tool_definitions(); + let mut tools = tool_definitions(); + if self.command_tool_allowed() { + tools.push(command_tool_definition()); + } // The runtime owns the exact instruction and tool metadata it sends. manifest.custom_instructions = custom_instructions.to_owned(); manifest.tool_schema_version = Some(TOOL_SCHEMA_VERSION.to_owned()); @@ -884,6 +1026,7 @@ impl<'a> TurnRuntime<'a> { data_directory: self.data_directory, session_id: self.journal.snapshot().session_id, workspace_id: self.workspace_id, + cancel: self.cancel.clone(), } .dispatch(call, self.limits.max_result_bytes); if let Some(filter) = self.tool_text_filter { @@ -971,14 +1114,25 @@ impl<'a> TurnRuntime<'a> { /// Any settings failure withholds them. The settings lock is released /// before the first model request. fn tool_replay_allowed(&self) -> bool { + self.workspace_permissions() + .is_some_and(|permissions| permissions.model_tools && permissions.read) + } + + /// Report whether the command tool may be advertised. It needs live + /// `model_tools`, `execute`, `read`, and `write`; each call rechecks them. + fn command_tool_allowed(&self) -> bool { + self.workspace_permissions().is_some_and(|permissions| { + permissions.model_tools && permissions.execute && permissions.read && permissions.write + }) + } + + /// Read the workspace's current preferences, releasing the settings lock. + fn workspace_permissions(&self) -> Option { match ControlStore::open_existing(self.data_directory) { Ok(Some(control)) => control .workspace(self.workspace_id) - .is_some_and(|workspace| { - let permissions = workspace.permissions(); - permissions.model_tools && permissions.read - }), - Ok(None) | Err(_) => false, + .map(|workspace| workspace.permissions()), + Ok(None) | Err(_) => None, } } @@ -1079,6 +1233,7 @@ struct WorkspaceToolDispatcher<'a> { data_directory: &'a Path, session_id: Uuid, workspace_id: WorkspaceId, + cancel: CancelToken, } impl WorkspaceToolDispatcher<'_> { @@ -1102,28 +1257,45 @@ impl WorkspaceToolDispatcher<'_> { ); } }; - let binding = match control.bind_session(self.session_id, self.workspace_id) { - Ok(binding) => binding, - Err(error) => { + // The persisted model-tool preference is rechecked on every call, so a + // change made during model I/O stops the next operation. + let permissions = match control.workspace(self.workspace_id) { + Some(workspace) => workspace.permissions(), + None => { return ToolExecution::denied( "policy_unavailable", call, - FileError::Control(error), + FileError::Denied(DecisionReason::PermissionDisabled), ); } }; - // The persisted model-tool preference is rechecked on every call, so a - // change made during model I/O stops the next operation. - let model_tools = control - .workspace(self.workspace_id) - .is_some_and(|workspace| workspace.permissions().model_tools); - if !model_tools { + if !permissions.model_tools { return ToolExecution::denied( "model_tools_disabled", call, FileError::Denied(DecisionReason::PermissionDisabled), ); } + if matches!(call.arguments, ToolArguments::Command { .. }) { + if !(permissions.execute && permissions.read && permissions.write) { + return ToolExecution::denied( + "command_disabled", + call, + FileError::Denied(DecisionReason::PermissionDisabled), + ); + } + return self.dispatch_command(control, call, max_result_bytes); + } + let binding = match control.bind_session(self.session_id, self.workspace_id) { + Ok(binding) => binding, + Err(error) => { + return ToolExecution::denied( + "policy_unavailable", + call, + FileError::Control(error), + ); + } + }; let target = FileTarget { session_id: self.session_id, workspace_id: self.workspace_id, @@ -1147,7 +1319,284 @@ impl WorkspaceToolDispatcher<'_> { Err(error) => classify_file_error(call, error), } } + ToolArguments::Command { .. } => ToolExecution::recoverable("invalid_command", call), + } + } + + /// Request or execute one command. The control store is dropped before the + /// run starts so the runner can take its own settings lock. + fn dispatch_command( + &self, + mut control: ControlStore, + call: &ToolCall, + max_result_bytes: usize, + ) -> ToolExecution { + let ToolArguments::Command { + profile, + program, + arguments, + cwd, + } = &call.arguments + else { + return ToolExecution::recoverable("invalid_command", call); + }; + let request = crate::run::RunRequest { + workspace_id: self.workspace_id, + profile: profile.clone(), + program: PathBuf::from(program), + arguments: arguments.iter().map(OsString::from).collect(), + working_directory: cwd.as_ref().map(PathBuf::from), + host_services: false, + network: false, + limits: command_limits(), + }; + let digest = command_digest(self.session_id, &request); + let now = now_unix(); + let revision = control.revision(); + let statuses = control.approval_statuses(now); + let matching = |state| { + statuses.iter().find(|status| { + status.session_id == self.session_id + && status.workspace_id == self.workspace_id + && status.operation == ApprovalOperation::Command + && status.request_sha256 == digest + && status.settings_revision == revision + && status.state == state + }) + }; + if let Some(approved) = matching(ApprovalState::Approved) { + let binding = ApprovalBinding { + session_id: self.session_id, + workspace_id: self.workspace_id, + operation: ApprovalOperation::Command, + request_sha256: digest, + }; + if let Err(error) = control.consume_approval(approved.id, &binding, now) { + return command_result( + call, + ToolOutcome::Failed, + "approval_failed", + json!({"error": error.to_string()}), + max_result_bytes, + ); + } + drop(control); + return self.execute_command(call, &request, max_result_bytes); + } + if let Some(pending) = matching(ApprovalState::Pending) { + return command_result( + call, + ToolOutcome::Failed, + "approval_required", + json!({ + "approval_id": pending.id, + "message": "The operator must approve this command before it can run.", + }), + max_result_bytes, + ); + } + if matching(ApprovalState::Denied).is_some() { + return command_result( + call, + ToolOutcome::Denied, + "approval_denied", + json!({"message": "The operator denied this command."}), + max_result_bytes, + ); } + let summary = command_summary(profile, program, arguments.len()); + let status = match control.request_approval( + &ApprovalDeclaration { + session_id: self.session_id, + workspace_id: self.workspace_id, + operation: ApprovalOperation::Command, + request_sha256: digest, + summary, + ttl_secs: COMMAND_APPROVAL_TTL_SECS, + }, + now, + ) { + Ok(status) => status, + Err(error) => { + return command_result( + call, + ToolOutcome::Failed, + "approval_failed", + json!({"error": error.to_string()}), + max_result_bytes, + ); + } + }; + drop(control); + command_result( + call, + ToolOutcome::Failed, + "approval_required", + json!({ + "approval_id": status.id, + "message": "The operator must approve this command before it can run.", + }), + max_result_bytes, + ) + } + + /// Run one approved command with a fixed, bounded request. + fn execute_command( + &self, + call: &ToolCall, + request: &crate::run::RunRequest, + max_result_bytes: usize, + ) -> ToolExecution { + let cancel = crate::run::CancelSignal::new(); + let stop = Arc::new(AtomicBool::new(false)); + let token = self.cancel.clone(); + let watcher = { + let cancel = cancel.clone(); + let stop = Arc::clone(&stop); + std::thread::spawn(move || { + while !stop.load(Ordering::SeqCst) { + if token.is_cancelled() { + cancel.cancel(); + break; + } + std::thread::sleep(Duration::from_millis(50)); + } + }) + }; + let result = crate::run::run(self.data_directory, request, &cancel); + stop.store(true, Ordering::SeqCst); + let _unreportable = watcher.join(); + match result { + Ok(report) => { + let body = json!({ + "tool": call.name.as_str(), + "status": "executed", + "result": report.finish.result, + "elapsed_ms": report.finish.elapsed_ms, + "stdout": report.stdout.text, + "stderr": report.stderr.text, + "stdout_truncated": report.stdout.truncated, + "stderr_truncated": report.stderr.truncated, + }); + let message = labelled_result(call, &body.to_string()); + if message.len() > max_result_bytes.min(MAX_MESSAGE_BYTES) { + return ToolExecution::recoverable("output_too_large", call); + } + ToolExecution::success(message) + } + Err(error) => command_result( + call, + ToolOutcome::Failed, + "command_failed", + json!({"error": error.to_string()}), + max_result_bytes, + ), + } + } +} + +/// Fixed limits for one model command run. +fn command_limits() -> crate::run::ProcessLimits { + crate::run::ProcessLimits { + deadline: COMMAND_DEADLINE, + max_stdout_bytes: COMMAND_OUTPUT_BYTES, + max_stderr_bytes: COMMAND_OUTPUT_BYTES, + tree: Some(crate::run::TreeLimits { + max_memory_bytes: 1024 * 1024 * 1024, + max_processes: 64, + max_cpu_time: Duration::from_secs(20), + max_disk_bytes: Some(256 * 1024 * 1024), + }), + ..crate::run::ProcessLimits::default() + } +} + +/// Bind one model command call to the exact run request. +fn command_digest(session_id: Uuid, request: &crate::run::RunRequest) -> String { + let mut bytes = Vec::new(); + push_field(&mut bytes, b"omgcode-command-v1"); + push_field(&mut bytes, session_id.as_bytes()); + push_field(&mut bytes, request.workspace_id.as_uuid().as_bytes()); + push_field(&mut bytes, request.profile.as_bytes()); + push_field(&mut bytes, request.program.as_os_str().as_encoded_bytes()); + push_field( + &mut bytes, + &u64::try_from(request.arguments.len()) + .unwrap_or(u64::MAX) + .to_le_bytes(), + ); + for argument in &request.arguments { + push_field(&mut bytes, argument.as_encoded_bytes()); + } + match &request.working_directory { + Some(directory) => push_field(&mut bytes, directory.as_os_str().as_encoded_bytes()), + None => push_field(&mut bytes, b""), + } + push_field( + &mut bytes, + &[u8::from(request.host_services), u8::from(request.network)], + ); + let tree = request.limits.tree; + let numbers = [ + u64::try_from(request.limits.deadline.as_millis()).unwrap_or(u64::MAX), + u64::try_from(request.limits.max_stdout_bytes).unwrap_or(u64::MAX), + u64::try_from(request.limits.max_stderr_bytes).unwrap_or(u64::MAX), + tree.map_or(0, |tree| tree.max_memory_bytes), + tree.map_or(0, |tree| u64::from(tree.max_processes)), + tree.map_or(0, |tree| { + u64::try_from(tree.max_cpu_time.as_millis()).unwrap_or(u64::MAX) + }), + tree.and_then(|tree| tree.max_disk_bytes).unwrap_or(0), + ]; + for number in numbers { + push_field(&mut bytes, &number.to_le_bytes()); + } + sha256_hex(&bytes) +} + +fn push_field(bytes: &mut Vec, value: &[u8]) { + bytes.extend(u64::try_from(value.len()).unwrap_or(u64::MAX).to_le_bytes()); + bytes.extend(value); +} + +/// A bounded operator-facing label for an approval request. +fn command_summary(profile: &str, program: &str, arguments: usize) -> String { + let label = Path::new(program) + .file_name() + .and_then(|name| name.to_str()) + .unwrap_or(program); + let mut summary = format!("run {profile}/{label} ({arguments} arguments)"); + if summary.len() > 180 { + summary.truncate(180); + while !summary.is_char_boundary(summary.len()) { + summary.pop(); + } + } + summary +} + +/// Render a command status as a bounded, source-labelled tool result. +fn command_result( + call: &ToolCall, + outcome: ToolOutcome, + code: &'static str, + detail: Value, + max_result_bytes: usize, +) -> ToolExecution { + let body = json!({ + "tool": call.name.as_str(), + "status": code, + "detail": detail, + }); + let message = labelled_result(call, &body.to_string()); + if message.len() > max_result_bytes.min(MAX_MESSAGE_BYTES) { + return ToolExecution::recoverable("output_too_large", call); + } + ToolExecution { + outcome, + code: Some(code), + text: message, + terminal: None, } } diff --git a/crates/omgcode-core/tests/turn_runtime.rs b/crates/omgcode-core/tests/turn_runtime.rs index 21a685e..b7e543a 100644 --- a/crates/omgcode-core/tests/turn_runtime.rs +++ b/crates/omgcode-core/tests/turn_runtime.rs @@ -3,14 +3,14 @@ use std::fs; use std::path::{Path, PathBuf}; use std::time::Duration; -use omgcode_core::control::ControlStore; +use omgcode_core::control::{ApprovalOperation, ApprovalState, ControlStore, now_unix}; use omgcode_core::policy::{PermissionSet, WorkspaceId}; use omgcode_core::prompt::{self, BASE_PROMPT, BASE_PROMPT_VERSION, ModelMessage, ModelRole}; use omgcode_core::session::{MessageRole, RequestManifest, SessionJournal}; use omgcode_core::turn::{ - CancelToken, ModelError, TOOL_SCHEMA_VERSION, ToolCallError, ToolModel, ToolModelReply, - ToolModelRequest, TurnError, TurnLimit, TurnLimits, TurnReport, TurnRuntime, - WITHHELD_TOOL_RESULT, + CancelToken, ModelError, TOOL_SCHEMA_VERSION, ToolArguments, ToolCall, ToolCallError, + ToolModel, ToolModelReply, ToolModelRequest, TurnError, TurnLimit, TurnLimits, TurnReport, + TurnRuntime, WITHHELD_TOOL_RESULT, }; use serde_json::{Value, json}; use tempfile::TempDir; @@ -259,6 +259,224 @@ fn read_events(path: &Path) -> Vec { .collect() } +#[test] +fn command_tool_arguments_are_strictly_validated() { + let parsed = ToolCall::parse(&call( + "cmd-1", + "workspace_run_command", + json!({ + "profile": "system", + "program": "cargo", + "arguments": ["test", "--all"], + "cwd": "sub" + }), + )) + .expect("valid command"); + match parsed.arguments { + ToolArguments::Command { + profile, + program, + arguments, + cwd, + } => { + assert_eq!(profile, "system"); + assert_eq!(program, "cargo"); + assert_eq!(arguments, vec!["test", "--all"]); + assert_eq!(cwd.as_deref(), Some("sub")); + } + other => panic!("unexpected arguments: {other:?}"), + } + + let too_many: Vec = (0..=64).map(|_| "x".to_owned()).collect(); + let oversized: Vec = (0..17).map(|_| "x".repeat(1024)).collect(); + for arguments in [ + json!({"profile": "system", "program": "cargo", "unknown": true}), + json!({"profile": "", "program": "cargo"}), + json!({"profile": "system", "program": "bad\nprogram"}), + json!({"profile": "system", "program": "cargo", "arguments": too_many}), + json!({"profile": "system", "program": "cargo", "arguments": oversized}), + ] { + assert!( + matches!( + ToolCall::parse(&call("cmd-1", "workspace_run_command", arguments)), + Err(ToolCallError::InvalidArguments) + ), + "arguments were accepted" + ); + } + assert!(matches!( + ToolCall::parse(&call( + "cmd-1", + "workspace_run_command", + json!({"profile": "system", "program": "cargo", "cwd": "../outside"}) + )), + Err(ToolCallError::InvalidPath) + )); +} + +/// A command call without an approval records a pending approval and does not +/// start a run. +#[test] +fn a_command_tool_call_requires_an_operator_approval() { + let mut fixture = Fixture::new(); + let workspace_id = fixture.workspace_id; + let session_id = fixture.snapshot().session_id; + let control = fixture.control_mut(); + control + .set_permissions( + workspace_id, + PermissionSet { + model_tools: true, + execute: true, + read: true, + write: true, + ..PermissionSet::default() + }, + control.revision(), + ) + .expect("enable command tools"); + let mut model = ScriptedModel::new(vec![ + tool_reply(vec![call( + "cmd-1", + "workspace_run_command", + json!({"profile": "system", "program": "echo", "arguments": ["hello"]}), + )]), + text_reply("approval requested"), + ]); + let report = fixture + .run(&mut model, TurnLimits::default()) + .expect("turn with a pending approval"); + assert_eq!(report.tool_calls, 1); + assert!( + model.requests[0] + .tools + .iter() + .any(|name| name == "workspace_run_command"), + "the command tool was not advertised" + ); + assert!( + fixture + .snapshot() + .messages + .iter() + .any(|message| message.text.contains("approval_required")), + "the tool result did not request an approval" + ); + fixture.close_journal(); + assert_eq!( + fixture.last_tool_code().as_deref(), + Some("approval_required") + ); + + let control = ControlStore::open_existing(&fixture.data) + .expect("open control") + .expect("control store"); + let statuses = control.approval_statuses(now_unix()); + let pending = statuses + .iter() + .find(|status| { + status.state == ApprovalState::Pending && status.operation == ApprovalOperation::Command + }) + .expect("a pending command approval"); + assert_eq!(pending.session_id, session_id); + assert_eq!(pending.workspace_id, workspace_id); + assert!(!fixture.data.join("runs-v1.jsonl").exists()); +} + +/// An approved command is consumed before the run is attempted. The fixture's +/// profile has no PATH entry, so the run is refused after consumption; this +/// proves the gate and the run hand-off without qualifying native execution. +#[test] +fn an_approved_command_consumes_the_approval_and_attempts_the_run() { + let mut fixture = Fixture::new(); + let workspace_id = fixture.workspace_id; + let tools = fixture._temporary.path().join("tools"); + fs::create_dir(&tools).expect("toolchain root"); + let control = fixture.control_mut(); + control + .set_permissions( + workspace_id, + PermissionSet { + model_tools: true, + execute: true, + read: true, + write: true, + ..PermissionSet::default() + }, + control.revision(), + ) + .expect("enable command tools"); + control + .add_profile( + &omgcode_core::control::ProfileDeclaration { + name: "system".into(), + read_only_roots: vec![tools], + path_entries: Vec::new(), + environment: Vec::new(), + }, + control.revision(), + ) + .expect("profile"); + + let command = || { + tool_reply(vec![call( + "cmd-1", + "workspace_run_command", + json!({"profile": "system", "program": "echo", "arguments": ["hello"]}), + )]) + }; + let mut first = ScriptedModel::new(vec![command(), text_reply("waiting")]); + fixture + .run(&mut first, TurnLimits::default()) + .expect("approval-request turn"); + fixture.release_control(); + + let mut control = ControlStore::open_existing(&fixture.data) + .expect("open control") + .expect("control store"); + let pending = control + .approval_statuses(now_unix()) + .into_iter() + .find(|status| status.state == ApprovalState::Pending) + .expect("pending approval"); + control + .decide_approval(pending.id, true, now_unix()) + .expect("approve"); + drop(control); + + let mut second = ScriptedModel::new(vec![command(), text_reply("attempted")]); + fixture + .run(&mut second, TurnLimits::default()) + .expect("approved turn"); + fixture.close_journal(); + assert_eq!(fixture.last_tool_code().as_deref(), Some("command_failed")); + + let control = ControlStore::open_existing(&fixture.data) + .expect("open control") + .expect("control store"); + let status = control + .approval_status(pending.id, now_unix()) + .expect("approval status"); + assert_eq!(status.state, ApprovalState::Consumed); +} + +/// The command tool is not advertised without the execute preference. +#[test] +fn the_command_tool_requires_execute() { + let mut fixture = Fixture::new(); + let mut model = ScriptedModel::new(vec![text_reply("text only")]); + fixture + .run(&mut model, TurnLimits::default()) + .expect("text turn"); + assert!( + !model.requests[0] + .tools + .iter() + .any(|name| name == "workspace_run_command"), + "the command tool was advertised without execute" + ); +} + #[test] fn allowed_read_and_list_produce_durable_source_labelled_results() { let mut fixture = Fixture::new(); diff --git a/docs/README.md b/docs/README.md index 0d3d896..7e9aade 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,8 @@ OMGCode has a Rust CLI prototype for local chat, JSONL sessions, and a bounded native workspace file broker. The broker is available only through trusted operator commands and, when a workspace enables `model_tools`, to the -local model's read and list tools. Other model tools are not implemented. The +local model's read, list, and approval-gated command tools. Model write, +network, Git, and MCP tools are not implemented. The trusted CLI `run` command runs one program under Linux Landlock or Windows AppContainer confinement with an operator-declared toolchain profile. No model tool starts a process. The guides distinguish implemented behaviour from the diff --git a/docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md b/docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md index 5888843..5381664 100644 --- a/docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md +++ b/docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md @@ -137,7 +137,7 @@ Limits and gaps: ## References -- [Workspace settings](../workspace-permissions.md#model-readlist-tools) +- [Workspace settings](../workspace-permissions.md#model-readlist-and-command-tools) - [ADR-0012](0012-separate-workspace-settings-from-execution-authority.md) - [ADR-0013](0013-enforce-file-access-with-native-handles-and-exclusive-creation.md) - [ADR-0016](0016-add-a-session-owned-tool-runtime-with-schema-v2.md) diff --git a/docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md b/docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md index ead2eea..8fe448f 100644 --- a/docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md +++ b/docs/adr/0030-run-trusted-commands-through-recorded-toolchain-profiles.md @@ -130,7 +130,8 @@ Facts observed during the work, on Windows 11 build 26300 and WSL 6.6: - **Capabilities:** `capabilities` reports `process_execution: "trusted_cli_only"` and `toolchain_profiles: true` on Linux and Windows. Settings diagnostics keep `execution_allowed: false`, because they do not - authorize a run. No model tool can start a process. + authorize a run. At that time, no model tool could start a process; ADR-0040 + later added an approval-gated command tool that calls the same runner. ## Alternatives considered diff --git a/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md b/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md index 9c931b3..59f8c01 100644 --- a/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md +++ b/docs/adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md @@ -67,8 +67,8 @@ Rules: ## Consequences -- A future model tool has a real per-call gate to call. No model tool, UI, or - execution path exists yet. +- ADR-0040 later added the command tool that consumes an approval. Until then, + no model tool, UI, or execution path existed. - The operator uses CLI commands until an approval UI exists. The CLI request command is a testing and manual-flow surface; a model tool would create the request through the same core method. diff --git a/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md new file mode 100644 index 0000000..8af68e8 --- /dev/null +++ b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md @@ -0,0 +1,96 @@ +# 0040: Gate the model command tool with approvals and the trusted runner + +- Status: Accepted +- Date: 2026-11-14 + +## Context + +Version 0.24.0 added trusted per-call approval records but no model tool +consumed one. The next model-authorised capability is a command tool: the +local model may request one confined program run under a recorded toolchain +profile. Chat is one non-interactive turn, so the operator approves between +turns rather than inside a prompt. + +Every process must still go through `omgcode_core::run::run`, the trusted +runner that applies live preferences, the profile, the run journal, and native +confinement. Prompt text and model claims grant nothing. + +## Decision + +Add the model tool `workspace_run_command`: + +1. **Offering:** the runtime advertises it only when the session workspace's + live `model_tools`, `execute`, `read`, and `write` preferences are enabled. + Each call rechecks them; the run checks them again. +2. **Arguments:** `profile`, `program`, `arguments` (at most 64 strings), and + an optional workspace-relative `cwd`. Parsing is strict: unknown fields, + invalid names, control characters in the program, oversized arguments, and + parent or absolute `cwd` values are refused. There is no shell; arguments + are passed exactly. +3. **Fixed limits:** the tool does not accept model-selected limits. It uses a + 20-second deadline, 32 KiB retained from each output stream, 1 GiB memory, + 64 processes, 20 seconds of CPU, and 256 MiB of disk growth. It selects no + network or host services. +4. **Approval binding:** the request digest covers the session, workspace, + profile, program, exact arguments, working directory, and fixed limits. + The operation is `command`. +5. **First call:** if no current approval matches, the runtime records a + pending approval with a bounded summary that contains no argument text and + returns `approval_required` with its identifier. Nothing runs. +6. **Approved call:** a matching approved, unexpired, unconsumed record is + consumed immediately before the run. The runtime drops the settings lock, + then calls the trusted runner. A settings change invalidates the approval. +7. **Denied, expired, and consumed records:** a denial returns + `approval_denied` without a new request. An expired or consumed record + causes a new pending request. A failed run consumes the approval; the model + or operator must request a new one. +8. **Records:** the session journal records the tool intent and result; the run + journal records the run intent and outcome. Output is untrusted, bounded, + and returned to the model. No replay executes a recorded call. + +The tool does not add a write, network, Git, or MCP tool. The `run` journal and +native confinement remain the authority and the only process path. + +## Alternatives considered + +- **Prompt-only approval or a model claim of approval.** Rejected: it is not + authority. +- **Automatic approval for a session or workspace.** Rejected: it authorizes + more than one exact request. +- **Model-selected limits or network access.** Rejected: the model cannot + widen its own resource or network boundary. +- **A shell command string.** Rejected: it would re-parse untrusted text and + break exact argument handling. +- **Direct unconfined execution from the model tool.** Rejected: the trusted + runner is the only process path. +- **A UI approval inside the chat turn.** Deferred: chat is non-interactive + today; the trusted CLI approval is the first operator surface. + +## Consequences + +- The operator flow is two turns: the model requests, the operator approves or + denies, then the model retries. The CLI exposes `approvals` commands; no UI + exists. +- The model can request a command but cannot approve it. A denied exact request + stays denied for the current settings revision. +- A run that fails after consumption uses the approval. Re-requesting is + explicit. +- The approval summary identifies the profile, program name, and argument + count, not the arguments. The operator must inspect the session tool intent + for the exact arguments before approving; the tool intent is untrusted + evidence. +- The tests cover parsing, the permission gate, approval creation, consumption, + and the run hand-off. They do not qualify a successful native command on both + hosts; the existing trusted-run tests and future acceptance work remain + separate. +- A model command can return up to 32 KiB per stream to the model; the turn's + result and aggregate limits still apply. + +## References + +- [Command execution](../execution.md#model-command-tool) +- [Agent instructions](../agent-instructions.md#approval-records) +- [Workspace settings](../workspace-permissions.md#model-readlist-and-command-tools) +- [Security coding rules](../security-coding-rules.md#process-and-sandbox-boundary) +- [Testing standards](../testing-standards.md) +- [ADR-0039](0039-gate-future-model-tools-with-bound-single-use-approval-records.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index c6a5f29..fed7b6b 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -54,3 +54,4 @@ meaningful alternative does not need an ADR. | [0037: Use a per-workspace cache root and a scoped Windows grant](0037-use-a-per-workspace-cache-root-and-a-scoped-windows-grant.md) | Accepted | 2026-11-14 | | [0038: Record provider profiles without credentials](0038-record-provider-profiles-without-credentials.md) | Accepted | 2026-11-14 | | [0039: Gate future model tools with bound, single-use approval records](0039-gate-future-model-tools-with-bound-single-use-approval-records.md) | Accepted | 2026-11-14 | +| [0040: Gate the model command tool with approvals and the trusted runner](0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md) | Accepted | 2026-11-14 | diff --git a/docs/agent-instructions.md b/docs/agent-instructions.md index 2d3dd9b..2c78fa4 100644 --- a/docs/agent-instructions.md +++ b/docs/agent-instructions.md @@ -32,18 +32,21 @@ skill/tool/memory selections, or an account profile. The core turn/tool runtime records the exact tool schema version and tool names in a schema-version-2 request manifest. Its read/list results are appended as -source-labelled user-level tool messages and are never system messages. Chat -runs this runtime only for a workspace that enables `model_tools`; otherwise it -sends no tool definitions and rejects any provider tool call. +source-labelled user-level tool messages and are never system messages. A +command result follows the same rule and remains untrusted. Chat runs this +runtime when the workspace enables `model_tools`; the command tool also needs +`execute`, `read`, and `write`, and it runs only after a trusted approval. +Otherwise chat sends no tool definitions and rejects any provider tool call. Prompt assembly limits custom instruction text and each history message to 16 KiB, history to 128 messages, and the assembled UTF-8 text to 256 KiB. The adapter applies a caller-supplied context budget using a byte-based estimate and fixed overhead. This is not an exact tokenizer or model-capacity check. The prototype has no settings UI, application/workspace/session preference store, -preview UI, token-count display, compaction, skills, memories, tools other -than chat's read/list workspace tools, or provider-specific subscription -routes. The current `--instructions` value is +preview UI, token-count display, compaction, skills, memories, model write, +network, Git, or MCP tools, or provider-specific subscription routes. Its only +model tools are read, list, and the approval-gated command tool. The current +`--instructions` value is per invocation, not a saved preference with scope or revision history. These statements describe implemented prototype behavior. The sections below @@ -158,7 +161,7 @@ Claude Code prompts. ## Approval records -A future model tool that changes host state must obtain a trusted, single-use +A model tool that changes host state must obtain a trusted, single-use approval record. `approvals request` records a pending request; `approvals list`, `show`, `approve`, and `deny` inspect or decide it; and `approvals consume` marks an approved record used. The record binds the @@ -166,13 +169,16 @@ session, workspace, operation, exact request SHA-256, and the settings revision at request time. It stores no argument text. The summary is at most 256 bytes, must contain no secrets or control characters, and is for the operator. -An approval lives 60 to 3600 seconds and is consumed at most once. Consumption -checks the binding and refuses if the settings revision changed. The CLI -consume command executes nothing. A future model tool must call the core -consumption check immediately before its operation and fail closed when the -record is missing, denied, expired, consumed, or bound differently. Approval -events preserve the settings revision. See -[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). +The `workspace_run_command` tool creates the request and consumes an approved +record immediately before calling the trusted runner. Its first call returns +`approval_required`; the operator approves between turns, and the model retries +the same call. An approval lives 60 to 3600 seconds and is consumed at most +once. Consumption checks the binding and refuses if the settings revision +changed. The CLI consume command executes nothing. The tool must fail closed +when the record is missing, denied, expired, consumed, or bound differently. +Approval events preserve the settings revision. See +[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md) +and [ADR-0040](adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). ## Release request records diff --git a/docs/development-tools.md b/docs/development-tools.md index 35bbc21..71f0a1f 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -25,7 +25,9 @@ the [tree limits](execution.md#tree-limits) for large builds. On Linux the process limit counts threads, so a parallel compiler needs a higher limit than its process count. Version 0.19.0 adds a sampled limit on net disk growth for the writable roots; it is not a filesystem quota. No -model tool runs project tools. Tool support must be qualified on the actual +model tool runs project tools. A model command tool can request one only +through the trusted `run` path and a consumed approval. Tool support must be +qualified on the actual platform; the [execution guide](execution.md#known-limits) lists the toolchains and versions that passed acceptance. diff --git a/docs/development.md b/docs/development.md index e8622b5..03f8a08 100644 --- a/docs/development.md +++ b/docs/development.md @@ -7,7 +7,8 @@ and save that conversation. It can read/list files, exclusively create new files/directories, and preview a bounded diff against trusted proposed content in a registered workspace. When a workspace enables `model_tools`, chat runs the core's bounded turn/tool runtime so the model can read and list files in -that workspace. Trusted CLI apply can +that workspace; with `execute`, `read`, and `write` enabled it can request an +approval-gated command. Trusted CLI apply can replace an existing file on Linux ext4 or Windows NTFS. Trusted restore puts a retained checkpoint's original bytes back through apply, and trusted checkpoint deletion removes one resolved private entry. The trusted `run` command starts @@ -19,7 +20,8 @@ time. A program started by `run` can create, change, and delete workspace files without a checkpoint. The CLI's `file` commands cannot delete workspace files, and the CLI cannot use Git or connect to MCP servers. When a workspace enables `model_tools`, chat lets the local model read and list -files in that workspace. Model write, process, network, Git, and MCP tools are +files in that workspace and, with execute/read/write, request an approval-gated +command. Model write, network, Git, and MCP tools are not implemented. Trusted commands record and apply the Windows container grants; see [command execution](execution.md). @@ -151,9 +153,11 @@ omgcode --data-dir C:\omgcode-data workspace container-revoke GRANT_UUID require existing state. Flags take explicit `true` or `false` values. Read/write default to enabled; execute, task-network, host-services, and model-tools default to disabled. All decisions still report `execution_allowed: false`; -only the trusted `run` command starts a process. Settings commands do not -dispatch tools. `--model-tools true` lets chat offer the model -read and list tools; see [model read/list tools](workspace-permissions.md#model-readlist-tools). +only the trusted `run` command starts a process, and the model command tool +reaches it only after consuming an approval. Settings commands do not dispatch +tools. `--model-tools true` lets chat offer the model read/list tools and, with +execute/read/write, the approval-gated command tool; see +[model tools](workspace-permissions.md#model-readlist-and-command-tools). See the [workspace contract](workspace-permissions.md) for limits and failures. `container-grant` and `container-revoke` work on Windows only. They change ACLs for the workspace's AppContainer and record each change; see @@ -221,9 +225,10 @@ native mount. Execute remains disabled. The `audit`, `acknowledge`, `checkpoints`, `acknowledge-checkpoint`, and `delete-checkpoint` commands require existing workspace settings. They do not require a configured root, workspace registration, or session -selection. Chat advertises the read and list tools only when the session's -workspace enables `model_tools`; see -[model read/list tools](workspace-permissions.md#model-readlist-tools). +selection. Chat advertises the read/list tools when the session's workspace +enables `model_tools`, and the command tool when `execute`, `read`, and `write` +are also enabled; see +[model tools](workspace-permissions.md#model-readlist-and-command-tools). Capability JSON separates implementation from availability. On Linux and Windows, `workspace_file_broker_implemented` is `true`, while @@ -470,7 +475,7 @@ usage events, streaming chunks, and large-output artifacts remain planned. | Crate | Responsibility | | --- | --- | | omgcode-core | Compiled prompt, bounded model adapter, session/control/file-operation/run journals, workspace policy and toolchain profiles, broker orchestration, trusted runs, bounded turn/tool lifecycle, and non-destructive edit previews | -| omgcode-cli | Trusted operator input, one-turn chat orchestration with optional read/list model tools, bounded file and preview commands, trusted `run`, JSON output | +| omgcode-cli | Trusted operator input, one-turn chat orchestration with optional read/list and approval-gated command model tools, bounded file and preview commands, trusted `run`, JSON output | | omgcode-platform | Native journal validation, directory identity, handle-relative workspace file operations, Windows AppContainer grants, interrupt-to-cancel handling, and a process-tree runner with Linux Landlock/seccomp and Windows AppContainer confinement | Core and CLI forbid unsafe code. The platform crate denies unsafe code except @@ -555,6 +560,7 @@ cargo test -p omgcode-cli --test toolchain_acceptance --locked -- --ignored Do not infer whole-user/process containment, Git safety, credential storage, release filesystem support, or full coding-agent support from these tests. The broker supports bounded file operations through trusted CLI input and the core -turn runtime, which chat drives for read and list when a workspace enables -`model_tools`. Live provider tool-call compatibility and process containment +turn runtime, which chat drives for read/list and an approval-gated command when +a workspace enables `model_tools`. Live provider tool-call compatibility and +process containment remain separate boundaries. diff --git a/docs/execution.md b/docs/execution.md index e459679..2aa35fd 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -26,11 +26,12 @@ Version 0.16.0 adds [trusted runs](#trusted-runs). `omgcode run` starts one program through `run_confined` under a recorded [toolchain profile](#toolchain-profiles), behind the workspace `execute` preference, and records it in the [run journal](#run-journal). It is a -trusted operator command only. No model tool starts a process, and nothing -calls the unconfined `run`. Settings diagnostics keep -`execution_allowed: false`, because a diagnostic never authorizes a run. Do -not describe either confinement as qualified beyond the tested kernel and -Windows build. +trusted operator command. A model command tool can request one, but only a +trusted approval record lets it call the same runner; no model tool starts a +process without that record, and nothing calls the unconfined `run`. Settings +diagnostics keep `execution_allowed: false`, because a diagnostic never +authorizes a run. Do not describe either confinement as qualified beyond the +tested kernel and Windows build. Version 0.17.0 adds [tree limits](#tree-limits): every trusted run is bounded in memory, live processes, and CPU time for its whole tree. Windows applies @@ -642,6 +643,35 @@ its cgroup. Do not place a development root under `/sys/fs/cgroup`. Other programs of the same user, outside the run, can still change the delegated cgroup. +### Model command tool + +Version 0.25.0 adds `workspace_run_command` to the core turn runtime. The +runtime advertises it only when the session workspace's live `model_tools`, +`execute`, `read`, and `write` preferences are enabled. Each call rechecks +them, and the trusted run checks them again. + +Arguments are a recorded toolchain `profile`, a `program`, at most 64 +`arguments`, and an optional workspace-relative `cwd`. There is no shell. +The tool fixes its limits: a 20-second deadline, 32 KiB retained from each +output stream, 1 GiB memory, 64 processes, 20 seconds of CPU, and 256 MiB of +disk growth. It selects no network or host services. + +The first call matches no approval, records a pending approval with a bounded +summary that contains no argument text, and returns `approval_required` with +the approval identifier. Nothing runs. The operator runs +`approvals approve `; the model must call again with the same arguments. +The runtime checks the exact digest, session, workspace, operation, and +settings revision, consumes the approval once, drops the settings lock, and +calls the trusted `run` path. A denial returns `approval_denied` and is not +re-requested. An expired or consumed record causes a new pending request. A +run that fails after consumption uses the approval. + +Output is untrusted and bounded. The session journal records the tool intent +and result; the run journal records the run. No replay executes a recorded +call. The model can request but cannot approve; the CLI approval commands are +the operator surface, and there is no approval UI. A successful native command +on both hosts remains a separate qualification. + ### Toolchain profiles Profiles are declared by the operator. Nothing is discovered automatically. @@ -954,6 +984,13 @@ These remain true after C6: back to application storage when no root is selected; Windows exposes nothing. There is no invalidation, eviction, or freshness check, and configuring a toolchain to use the directory is operator work. +- **Model command limits.** The model command tool accepts no model-selected + limits, network, or host services. It uses a 20-second deadline and 32 KiB + per output stream. The operator flow spans two turns, and no approval UI + exists. A denied exact request stays denied for the current settings + revision; a failed run consumes the approval. The gate and hand-off are + tested, but a successful native command on both hosts is not yet qualified + as a model-tool acceptance case. - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -1009,10 +1046,13 @@ These remain true after C6: | C10 (0.21.0) | Trusted allowlisted package fetch | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0035. The run remains offline. | | C11 (0.22.0) | Read-only package cache for Linux runs | Superseded by C12: Linux exposure moved to the per-workspace root, with an application-storage fallback. | | C12 (0.23.0) | Per-workspace package cache root and scoped Windows grant | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0037. Windows needs a read-execute grant on the workspace root. | +| C13 (0.24.0) | Provider profiles and trusted approval records | Done: see the [provider authentication guide](provider-authentication.md#recorded-provider-profiles-0240) and [approval records](agent-instructions.md#approval-records). No adapter or model tool executed. | +| C14 (0.25.0) | Approval-gated model command tool | Done: see [model command tool](#model-command-tool) and ADR-0040. A successful native command still needs its own qualification. | Later work needs its own decisions: - registry credentials and development-server networking; -- a model-callable command tool. +- model write, network, Git, and MCP tools; +- native successful-command qualification for the model tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/file-access.md b/docs/file-access.md index f937e28..44377ab 100644 --- a/docs/file-access.md +++ b/docs/file-access.md @@ -7,7 +7,7 @@ new-file creation, and exclusive single-directory creation. Trusted CLI input exercises these APIs. The 0.4.0 core turn runtime can also dispatch read and list through a caller-supplied model interface. Since 0.12.0, chat runs that runtime with the local LM Studio adapter when the workspace's -[`model_tools` preference](workspace-permissions.md#model-readlist-tools) is +[`model_tools` preference](workspace-permissions.md#model-readlist-and-command-tools) is enabled; otherwise chat advertises no tools. The 0.5.0 CLI adds a read-only `file diff` preview that reads through the broker and never writes, checkpoints, or replaces a workspace entry. The process runner, diff --git a/docs/platform-support.md b/docs/platform-support.md index 962e4b6..2dfa264 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -19,7 +19,7 @@ containment. | User-project toolchains | Required; native installed/managed profile matrix not yet qualified | | Workspace directory identity | Configuration-only metadata check; required native ID and creation time must be available | | Workspace file broker | Bounded read/list/exclusive-create/single-directory creation through trusted CLI commands; release filesystem support is not qualified | -| Model file tools | Read and list only, through chat, for a workspace that enables `model_tools`; write and general file tools are disabled and `workspace_file_tools` remains false | +| Model file tools | Read and list, plus an approval-gated command tool, through chat for a workspace that enables `model_tools` (and `execute`, `read`, `write` for commands); write and general file tools are disabled and `workspace_file_tools` remains false | | Process-tree runner | Called only by the trusted CLI `run`, through `run_confined`. Windows uses a Job Object assigned at creation and a per-workspace AppContainer. Linux uses a process group, seccomp, `close_range` (kernel 5.11 or later, x86_64 or aarch64), and Landlock ABI 3 or later. Tested on Windows 11 build 26300 and WSL 6.6 only ([execution](execution.md)) | | Tree limits | Every trusted run. Windows uses job memory and active-process limits and job CPU accounting. Linux needs a delegated cgroup v2 with `memory` and `pids` (Linux 5.14 or later for `cgroup.kill`), normally from a `systemd-run --user` scope, so it needs a user service manager. Disk growth is sampled by the supervisor on both platforms; it is not a filesystem quota. Tested on Windows 11 build 26300 and WSL 6.6 only ([tree limits](execution.md#tree-limits)) | | Package networking | Profiles are recorded on both platforms; no run accepts one, `--network` remains all-or-nothing, and no unprivileged destination filter exists on either platform. The trusted `packages fetch` command uses system TLS trust and a per-workspace cache root. The root is exposed read-only on Linux and Windows; Windows needs a read-execute container grant and traversable ancestors, and Linux falls back to application storage when no root is selected (ADR-0034, ADR-0035, ADR-0037) ([fetch](execution.md#trusted-package-fetch)) | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 7b5c916..0aa9787 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -235,6 +235,12 @@ crate. request digest, and settings revision. Refuse a missing, denied, expired, consumed, mismatched, or settings-invalidated record. Prompt text, model claims, and recorded intents never grant authority. See ADR-0039. +- The `workspace_run_command` model tool may be advertised only under live + `model_tools`, `execute`, `read`, and `write`. Its first call records a + pending approval and starts nothing; only a later exact call may consume an + approved record and call the trusted runner. The model cannot approve, + select limits, use a shell, select network or host services, or reuse an + approval. Treat its output as untrusted. See ADR-0040. - Do not enforce a package or task destination list with proxy environment variables or an advisory loopback proxy: a confined tree can ignore them and connect directly. A package-network profile is configuration only until a diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 7d13804..7c17572 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -159,6 +159,7 @@ As the relevant components are implemented, include: | Windows confinement | Granted read-only and read-write paths, denied host files, directories, named pipe, and loopback TCP, a writable container temporary directory, inheritance by descendants, the same probes unconfined, missing, weaker, and foreign grants, a missing profile, `LOCALAPPDATA`, or container name, refused `HostServices`, an ungranted program | | Container grants | SID derivation, propagation to existing and new children, exact read-back, protection state kept, junctions not followed, hard-link reach, refused replaced/junction/file/relative paths, profile creation and deletion, journal intent and outcome order, replay validation, revision rules, scope refusals, pending and revoking recovery, the revocation reserve, CLI grant/list/revoke, refusal off Windows | | Model tool chat | Preference off by default and rechecked per call, settings compatibility, confinement against parent, absolute, rooted, UNC, link, junction, and hard-link paths, strict provider tool-call parsing, token removal before journal and model, refusal of token-bearing calls, withheld replay after revocation, finish reason, one call per turn in escape cases | +| Model command tool | Strict profile/program/argument/cwd parsing, tool advertised only with live model-tools/execute/read/write, first call records a pending approval and starts nothing, denial, approval consumption, exact digest and binding, settings-revision invalidation, run hand-off failure, output bounds, and no replay | | MCP | Version/transport compatibility, authorization, untrusted content, local confinement, OAuth/redirects, cancellation | | LM Studio | Model discovery, token/no-token profiles, streamed tools, context limits, unavailable models, no hosted-tool bypass | | Instructions | Compiled base/UI/request match, runtime replacement denial, role-injection attempts, preference/task precedence, revisions, safe rendering | diff --git a/docs/workspace-permissions.md b/docs/workspace-permissions.md index 26a044e..f9b46c9 100644 --- a/docs/workspace-permissions.md +++ b/docs/workspace-permissions.md @@ -30,7 +30,7 @@ Read and write preferences default to enabled; process execution, task network access, host services, and model tools default to disabled. Provider connections remain separate from task networking. No operation class executes a tool by itself. The separate `model_tools` and `host_services` preferences -are described under [model read/list tools](#model-readlist-tools) and +are described under [model tools](#model-readlist-and-command-tools) and [host services](#host-services). Registration stores the canonical native path, volume/filesystem ID, 128-bit @@ -236,11 +236,13 @@ trusted per-call approvals. A request records a session, workspace, operation, exact request digest, summary, settings revision, and expiry. The events `approval_requested`, `approval_decided`, and `approval_consumed` preserve the settings revision. A decision or consumption is refused after expiry, -mismatch, reuse, or any settings change. No model tool consumes an approval -yet, and the CLI consume command executes nothing. The +mismatch, reuse, or any settings change. The `workspace_run_command` model tool +consumes an approval; the CLI consume command marks a record used but executes +nothing. The [agent instructions guide](agent-instructions.md#approval-records) owns the tool-side contract. See -[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md). +[ADR-0039](adr/0039-gate-future-model-tools-with-bound-single-use-approval-records.md) +and [ADR-0040](adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). ## Task network @@ -268,7 +270,7 @@ log. Host-service access exposes every Unix socket the user can reach, including the Docker daemon; see [Unix-domain sockets](execution.md#unix-domain-sockets). -## Model read/list tools +## Model read/list and command tools `workspace permissions --revision --model-tools true` lets `chat` offer the local model two tools for that workspace: `workspace_read_file` and @@ -278,6 +280,15 @@ other flags. It needs the expected revision, appends `permissions_changed`, and increments the revision. It is not an operation class, so `workspace check` and policy audit records do not mention it. +When `model_tools`, `execute`, `read`, and `write` are all enabled, the runtime +also offers `workspace_run_command`. Its first call records a pending approval +and does not run; after `approvals approve `, a second identical call +consumes the approval and starts the trusted run. The model cannot approve. +The tool uses fixed limits and no network or host services. See +[model command tool](execution.md#model-command-tool) and +[ADR-0040](adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). +The tool schema version is 0.2.0. + `workspace status` always reports `model_tools`. Persisted settings omit the field while it is `false`, so settings that never enable it keep their exact bytes and remain readable by version 0.11.0. Once a `true` value is written, From 338722d765deff5adb8fbd0553186f91973243b0 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 10:47:32 +0000 Subject: [PATCH 10/17] fix: fit model command output inside the tool result bound Retain 4 KiB from each command stream instead of 32 KiB. The turn's tool message is capped at 16 KiB, so the larger capture could replace a useful result with output_too_large. Co-Authored-By: Claude Code --- CHANGELOG.md | 2 +- crates/omgcode-core/src/turn.rs | 2 +- ...l-command-tool-with-approvals-and-the-trusted-runner.md | 7 ++++--- docs/execution.md | 4 ++-- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cfeaf9..a88c542 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ Changes are recorded here before a release version is assigned. `approval_required`; it starts nothing. After `approvals approve `, a second identical call consumes the approval and calls the trusted runner. The model cannot approve, select limits, or select network/host services. - - **Limits:** 20-second deadline, 32 KiB per output stream, 1 GiB memory, + - **Limits:** 20-second deadline, 4 KiB per output stream, 1 GiB memory, 64 processes, 20 seconds of CPU, and 256 MiB of disk growth. - **Records:** the session journal records the tool intent/result; the run journal records the run. A failed run consumes the approval; no replay diff --git a/crates/omgcode-core/src/turn.rs b/crates/omgcode-core/src/turn.rs index 62a630a..76138c0 100644 --- a/crates/omgcode-core/src/turn.rs +++ b/crates/omgcode-core/src/turn.rs @@ -72,7 +72,7 @@ pub const MAX_COMMAND_PROGRAM_BYTES: usize = 1024; /// Deadline for one model command run. pub const COMMAND_DEADLINE: Duration = Duration::from_secs(20); /// Retained bytes from each model command output stream. -pub const COMMAND_OUTPUT_BYTES: usize = 32 * 1024; +pub const COMMAND_OUTPUT_BYTES: usize = 4 * 1024; /// Approval lifetime requested by a model command call. pub const COMMAND_APPROVAL_TTL_SECS: u64 = 900; diff --git a/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md index 8af68e8..d1a13be 100644 --- a/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md +++ b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md @@ -28,7 +28,7 @@ Add the model tool `workspace_run_command`: parent or absolute `cwd` values are refused. There is no shell; arguments are passed exactly. 3. **Fixed limits:** the tool does not accept model-selected limits. It uses a - 20-second deadline, 32 KiB retained from each output stream, 1 GiB memory, + 20-second deadline, 4 KiB retained from each output stream, 1 GiB memory, 64 processes, 20 seconds of CPU, and 256 MiB of disk growth. It selects no network or host services. 4. **Approval binding:** the request digest covers the session, workspace, @@ -83,8 +83,9 @@ native confinement remain the authority and the only process path. and the run hand-off. They do not qualify a successful native command on both hosts; the existing trusted-run tests and future acceptance work remain separate. -- A model command can return up to 32 KiB per stream to the model; the turn's - result and aggregate limits still apply. +- A model command can return up to 4 KiB per stream; the turn's result and + aggregate limits still apply, and a larger result is replaced with a + controlled `output_too_large` result. ## References diff --git a/docs/execution.md b/docs/execution.md index 2aa35fd..0ed3c78 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -652,7 +652,7 @@ them, and the trusted run checks them again. Arguments are a recorded toolchain `profile`, a `program`, at most 64 `arguments`, and an optional workspace-relative `cwd`. There is no shell. -The tool fixes its limits: a 20-second deadline, 32 KiB retained from each +The tool fixes its limits: a 20-second deadline, 4 KiB retained from each output stream, 1 GiB memory, 64 processes, 20 seconds of CPU, and 256 MiB of disk growth. It selects no network or host services. @@ -985,7 +985,7 @@ These remain true after C6: nothing. There is no invalidation, eviction, or freshness check, and configuring a toolchain to use the directory is operator work. - **Model command limits.** The model command tool accepts no model-selected - limits, network, or host services. It uses a 20-second deadline and 32 KiB + limits, network, or host services. It uses a 20-second deadline and 4 KiB per output stream. The operator flow spans two turns, and no approval UI exists. A denied exact request stays denied for the current settings revision; a failed run consumes the approval. The gate and hand-off are From 299c71887e5185cc9b8bf70c8fe1c80d025df23d Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 11:13:12 +0000 Subject: [PATCH 11/17] test: qualify the model command tool on both hosts Drive the real chat CLI, a mock provider, an operator approval, and the trusted runner through one successful confined command. The first turn records approval_required; the operator approves; the second identical turn consumes the record and exits 0. Update the qualification claims and evidence in the changelog, ADR, execution guide, and testing standards. Co-Authored-By: Claude Code --- CHANGELOG.md | 9 +- crates/omgcode-cli/tests/model_tools.rs | 153 ++++++++++++++++++ crates/omgcode-cli/tests/support/mod.rs | 2 +- ...l-with-approvals-and-the-trusted-runner.md | 8 +- docs/execution.md | 18 ++- docs/testing-standards.md | 12 +- 6 files changed, 187 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a88c542..19408ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,8 +22,13 @@ Changes are recorded here before a release version is assigned. - **Records:** the session journal records the tool intent/result; the run journal records the run. A failed run consumes the approval; no replay executes a recorded call. - - **Not qualified:** a successful native command on both hosts as a - model-tool acceptance case; the gate and run hand-off are tested. + - **Qualified:** a successful approved command through the real chat CLI on + both hosts. A mock provider requests the platform shell's `echo`; the first + turn records `approval_required`, the operator approves, and the second + identical turn consumes the record and runs the command through the trusted + runner. The test asserts an `exited` result with code 0, the bounded output, + the session tool result, and the consumed approval. On Linux the CLI starts + in a delegated cgroup; on Windows the scene grants the workspace. - Version 0.24.0 records provider profiles and trusted per-call approvals. See ADR-0038 and ADR-0039. - **Provider profiles:** `workspace provider-profile-add/show/remove` record diff --git a/crates/omgcode-cli/tests/model_tools.rs b/crates/omgcode-cli/tests/model_tools.rs index 8b6229e..c9ae414 100644 --- a/crates/omgcode-cli/tests/model_tools.rs +++ b/crates/omgcode-cli/tests/model_tools.rs @@ -13,6 +13,7 @@ use std::time::{Duration, Instant}; use serde_json::{Value, json}; +use support::run_scene::{Scene, run_command, shell}; use support::workspace_fixture::Fixture; use support::{ CLI_DEADLINE, HANG_FIXTURE_ENV, assert_error_code, assert_success, json_output, path_arg, @@ -581,6 +582,158 @@ fn revoking_read_denies_model_reads_even_with_tools_enabled() { assert!(!events.contains(std::str::from_utf8(NOTE).expect("UTF-8 note"))); } +/// Start chat under the delegated cgroup a confined run needs. +/// +/// A chat turn can perform an approved model command in the same process, and +/// on Linux the trusted runner refuses a process outside a delegated cgroup. +/// `run_command` places the CLI in a `Delegate=yes` scope there and is a plain +/// CLI launcher on Windows. +fn scoped_chat(scene: &Scene, journal: &Path, endpoint: &str, message: &str) -> Output { + let journal = path_arg(journal); + let arguments = [ + "chat", + "--journal", + journal, + "--endpoint", + endpoint, + "--model", + "fixture", + "--context-tokens", + "131072", + "--max-output-tokens", + "64", + message, + ]; + let result = run_with_deadline( + run_command(&scene.data, &arguments), + Duration::from_secs(60), + ) + .expect("run OMGCode chat"); + assert!( + !result.timed_out, + "chat exceeded its deadline: stdout={} stderr={}", + String::from_utf8_lossy(&result.output.stdout), + String::from_utf8_lossy(&result.output.stderr) + ); + result.output +} + +/// The full operator flow: the model asks for one command, the operator +/// approves the exact request between turns, and the approved turn runs a real +/// confined program through the trusted runner on the host. +#[test] +fn an_approved_model_command_runs_successfully_through_the_trusted_runner() { + let scene = Scene::build(true, true); + for permission in ["--read", "--write", "--model-tools"] { + scene.set_permission(permission, "true"); + } + assert_success(&scene.add_profile("system", &[])); + + let session = scene.cli(&["session", "new", "--workspace", path_arg(&scene.workspace)]); + assert_success(&session); + let journal = PathBuf::from(json_output(&session)["journal"].as_str().expect("journal")); + + // The platform shell is the program; the tool itself has no shell mode and + // passes every argument exactly as the model provided it. + let command = shell("echo approved"); + let request = json!({ + "profile": "system", + "program": command[0], + "arguments": &command[1..], + }); + + let server = SequenceServer::start(vec![ + tool_call("call-1", "workspace_run_command", &request), + text("Waiting for operator approval."), + ]); + let first = scoped_chat(&scene, &journal, &server.endpoint, "run the command"); + let requests = server.finish(); + + assert_success(&first); + let first = json_output(&first); + assert_eq!(first["reply"]["content"], "Waiting for operator approval."); + assert_eq!(first["model_tools"]["tool_calls"], 1); + assert_eq!(requests.len(), 2); + let offered = requests[0]["tools"].to_string(); + assert!( + offered.contains("workspace_run_command"), + "the command tool must be offered: {offered}" + ); + + let listed = scene.cli(&["approvals", "list"]); + assert_success(&listed); + let approvals = json_output(&listed)["approvals"] + .as_array() + .expect("approvals") + .to_vec(); + assert_eq!(approvals.len(), 1, "one pending request: {approvals:?}"); + assert_eq!(approvals[0]["operation"], "command"); + assert_eq!(approvals[0]["state"], "pending"); + let approval = approvals[0]["id"].as_str().expect("approval id").to_owned(); + assert_success(&scene.cli(&["approvals", "approve", &approval])); + + let server = SequenceServer::start(vec![ + tool_call("call-2", "workspace_run_command", &request), + text("The command finished."), + ]); + let second = scoped_chat(&scene, &journal, &server.endpoint, "run the command"); + let requests = server.finish(); + + assert_success(&second); + let second = json_output(&second); + assert_eq!(second["reply"]["content"], "The command finished."); + assert_eq!(second["model_tools"]["tool_calls"], 1); + assert_eq!(requests.len(), 2); + let result = user_texts(&requests[1]) + .into_iter() + .find(|text| text.starts_with("Tool result [call call-2")) + .expect("executed command result sent to the model"); + assert!( + result.contains("\"status\":\"executed\""), + "the model must receive the executed result: {result}" + ); + let expected_stdout = if cfg!(windows) { + "\"stdout\":\"approved\\r\\n\"" + } else { + "\"stdout\":\"approved\\n\"" + }; + assert!( + result.contains(expected_stdout), + "the confined program output must reach the model: {result}" + ); + + let events = fs::read_to_string(&journal).expect("session journal"); + assert!(events.contains("tool.completed")); + assert!( + events.contains("\\\"status\\\":\\\"executed\\\""), + "the session journal must record the executed result: {events}" + ); + + let audit = scene.audit(); + assert_eq!(audit["pending"], json!([])); + let finished: Vec<&Value> = audit["entries"] + .as_array() + .expect("entries") + .iter() + .filter(|entry| entry["action"]["type"] == "run_finished") + .collect(); + assert_eq!(finished.len(), 1, "exactly one run: {audit}"); + assert_eq!( + finished[0]["action"]["payload"]["finish"]["result"], + json!({"kind": "exited", "code": 0}), + "the confined program must exit successfully" + ); + + let listed = scene.cli(&["approvals", "list"]); + assert_success(&listed); + let listed = json_output(&listed); + let approvals = listed["approvals"].as_array().expect("approvals"); + assert_eq!(approvals.len(), 1); + assert_eq!(approvals[0]["state"], "consumed"); + + scene.close(); +} + #[test] fn invalid_settings_stop_chat_before_any_model_request() { let fixture = Fixture::new(NOTE); diff --git a/crates/omgcode-cli/tests/support/mod.rs b/crates/omgcode-cli/tests/support/mod.rs index c04defb..d525723 100644 --- a/crates/omgcode-cli/tests/support/mod.rs +++ b/crates/omgcode-cli/tests/support/mod.rs @@ -2,7 +2,7 @@ #[allow( dead_code, - reason = "only run workflow test binaries use the run scene" + reason = "only the run workflow and model command test binaries use the run scene" )] pub(crate) mod run_scene; pub(crate) mod spawn_gate; diff --git a/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md index d1a13be..632e953 100644 --- a/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md +++ b/docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md @@ -80,9 +80,11 @@ native confinement remain the authority and the only process path. for the exact arguments before approving; the tool intent is untrusted evidence. - The tests cover parsing, the permission gate, approval creation, consumption, - and the run hand-off. They do not qualify a successful native command on both - hosts; the existing trusted-run tests and future acceptance work remain - separate. + and the run hand-off. A CLI acceptance test now drives the real chat process + through both turns with a mock provider and an operator approval, then runs a + successful confined command through the trusted runner on both Linux and + Windows. It needs a delegated cgroup on Linux and a workspace container grant + on Windows; a host without them fails the case rather than skipping it. - A model command can return up to 4 KiB per stream; the turn's result and aggregate limits still apply, and a larger result is replaced with a controlled `output_too_large` result. diff --git a/docs/execution.md b/docs/execution.md index 0ed3c78..fc2dc8b 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -669,8 +669,11 @@ run that fails after consumption uses the approval. Output is untrusted and bounded. The session journal records the tool intent and result; the run journal records the run. No replay executes a recorded call. The model can request but cannot approve; the CLI approval commands are -the operator surface, and there is no approval UI. A successful native command -on both hosts remains a separate qualification. +the operator surface, and there is no approval UI. A CLI acceptance test runs +one approved command through the real chat process, a mock provider, and the +trusted runner on both Linux and Windows, and asserts a successful exit, the +bounded output, and the consumed approval. On Linux the chat process starts in +a delegated cgroup; on Windows the test scene grants the workspace. ### Toolchain profiles @@ -988,9 +991,11 @@ These remain true after C6: limits, network, or host services. It uses a 20-second deadline and 4 KiB per output stream. The operator flow spans two turns, and no approval UI exists. A denied exact request stays denied for the current settings - revision; a failed run consumes the approval. The gate and hand-off are - tested, but a successful native command on both hosts is not yet qualified - as a model-tool acceptance case. + revision; a failed run consumes the approval. A CLI acceptance test runs one + approved command through the real chat process and the trusted runner on + both hosts; it needs a delegated cgroup on Linux and a workspace container + grant on Windows. Confinement correctness remains the platform suites' + responsibility. - **Network coverage.** Network access was tested on Windows 11 build 26300 and WSL 6.6 (Landlock ABI 3) only, including a TLS fetch with the system `curl` on both. The ABI 4 TCP-bind denial has not run on a live kernel. @@ -1047,12 +1052,11 @@ These remain true after C6: | C11 (0.22.0) | Read-only package cache for Linux runs | Superseded by C12: Linux exposure moved to the per-workspace root, with an application-storage fallback. | | C12 (0.23.0) | Per-workspace package cache root and scoped Windows grant | Done: see [trusted package fetch](#trusted-package-fetch) and ADR-0037. Windows needs a read-execute grant on the workspace root. | | C13 (0.24.0) | Provider profiles and trusted approval records | Done: see the [provider authentication guide](provider-authentication.md#recorded-provider-profiles-0240) and [approval records](agent-instructions.md#approval-records). No adapter or model tool executed. | -| C14 (0.25.0) | Approval-gated model command tool | Done: see [model command tool](#model-command-tool) and ADR-0040. A successful native command still needs its own qualification. | +| C14 (0.25.0) | Approval-gated model command tool | Done: see [model command tool](#model-command-tool) and ADR-0040. A CLI acceptance test qualifies one successful approved command on both hosts; confinement correctness remains the platform suites' responsibility. | Later work needs its own decisions: - registry credentials and development-server networking; - model write, network, Git, and MCP tools; -- native successful-command qualification for the model tool. Live qualification on each supported OS remains a separate gate. diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 7c17572..bc7b11e 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -159,7 +159,7 @@ As the relevant components are implemented, include: | Windows confinement | Granted read-only and read-write paths, denied host files, directories, named pipe, and loopback TCP, a writable container temporary directory, inheritance by descendants, the same probes unconfined, missing, weaker, and foreign grants, a missing profile, `LOCALAPPDATA`, or container name, refused `HostServices`, an ungranted program | | Container grants | SID derivation, propagation to existing and new children, exact read-back, protection state kept, junctions not followed, hard-link reach, refused replaced/junction/file/relative paths, profile creation and deletion, journal intent and outcome order, replay validation, revision rules, scope refusals, pending and revoking recovery, the revocation reserve, CLI grant/list/revoke, refusal off Windows | | Model tool chat | Preference off by default and rechecked per call, settings compatibility, confinement against parent, absolute, rooted, UNC, link, junction, and hard-link paths, strict provider tool-call parsing, token removal before journal and model, refusal of token-bearing calls, withheld replay after revocation, finish reason, one call per turn in escape cases | -| Model command tool | Strict profile/program/argument/cwd parsing, tool advertised only with live model-tools/execute/read/write, first call records a pending approval and starts nothing, denial, approval consumption, exact digest and binding, settings-revision invalidation, run hand-off failure, output bounds, and no replay | +| Model command tool | Strict profile/program/argument/cwd parsing, tool advertised only with live model-tools/execute/read/write, first call records a pending approval and starts nothing, denial, approval consumption, exact digest and binding, settings-revision invalidation, run hand-off failure, output bounds, and no replay. An end-to-end CLI case drives the real chat process, a mock provider, an operator approval, and the trusted runner to a successful confined command on both hosts | | MCP | Version/transport compatibility, authorization, untrusted content, local confinement, OAuth/redirects, cancellation | | LM Studio | Model discovery, token/no-token profiles, streamed tools, context limits, unavailable models, no hosted-tool bypass | | Instructions | Compiled base/UI/request match, runtime replacement denial, role-injection attempts, preference/task precedence, revisions, safe rendering | @@ -178,7 +178,15 @@ Completions request and rejects any tool call in the reply. It requires the compiled base prompt and accepts only a literal loopback HTTP endpoint. The adapter is not a permission boundary: the CLI selects tool mode from the live `model_tools` preference, and the runtime rechecks that preference before each -call. The turn-runtime tests use a scripted model interface. The tool-enabled chat tests +call. An end-to-end acceptance case starts the real chat CLI under a delegated +cgroup on Linux, has the mock provider request the platform shell's `echo`, +approves the recorded call between turns, and asserts that the second identical +turn consumes the approval and runs the command through the trusted runner to +an `exited` result with code 0 and the expected output. On Windows the scene +grants the workspace. The case needs those host facilities and fails without +them; it does not qualify confinement correctness, which the platform suites +own. It passed on Windows 11 build 26300 and WSL 6.6 (Ubuntu 24.04) on +2026-11-14. The turn-runtime tests use a scripted model interface. The tool-enabled chat tests use a mock that returns the documented OpenAI-compatible tool-call shape; they do not establish live LM Studio tool-call compatibility. A single opt-in spot-check with LM Studio 0.4.28 and `google/gemma-4-e4b` on Windows is recorded in the implementation plan. Model discovery, streaming, cancellation, and From c034c6c1a39cb4becf7cb656acfb8b967d3c7b48 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 11:13:14 +0000 Subject: [PATCH 12/17] docs: correct model command status in the plan Stop listing model process execution and per-call approval as unimplemented, describe the command tool in the chat guides, and record the 0.25.0 version and C15 qualification. Co-Authored-By: Claude Code --- IMPLEMENTATION_PLAN.md | 38 ++++++++++++++++++++++++-------------- docs/development.md | 26 +++++++++++++++----------- 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index af9a4d7..1422b83 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -1,6 +1,6 @@ # OMGCode implementation plan -Last verified: 2026-11-13. +Last verified: 2026-11-14. This guide is part of `main` after PR #9. Read it before selecting the next increment. Checkpoint preparation does not mean native replacement exists. @@ -68,7 +68,9 @@ This is a resume guide, not a replacement for the owning contracts in cache roots and scoped Windows access (ADR-0037), **Phase C13**, version **0.24.0**, with provider-profile records and trusted per-call approvals (ADR-0038, ADR-0039), and **Phase C14**, version **0.25.0**, with the - approval-gated model command tool (ADR-0040). It is stacked on C7 at + approval-gated model command tool (ADR-0040), qualified by **Phase C15**, a + native end-to-end acceptance test of one approved successful command on both + hosts. It is stacked on C7 at `0426e42`. No run accepts a profile or has destination-scoped networking; no provider adapter is enabled, and the command tool is the only model tool that can request a process. @@ -95,9 +97,11 @@ Implemented today: complete proposed UTF-8 content. Exact digests, bounded one-hunk diff, no workspace mutation, no checkpoint, no replacement. - LM Studio Chat Completions chat with non-streaming requests. It is text-only - unless the session's workspace enables `model_tools`; then it offers only the - read and list tools. See - [ADR-0026](docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md). + unless the session's workspace enables `model_tools`; then it offers the read + and list tools and, when `execute`, `read`, and `write` also allow it, the + approval-gated command tool. See + [ADR-0026](docs/adr/0026-offer-read-list-tools-through-a-workspace-preference.md) + and [ADR-0040](docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). - Read-only core initialization/ledger record inspectors with bounded strict JSON, lifecycle validation, manifest references, and unresolved-state retention. The pure inspectors open no files and execute no recorded work. @@ -157,8 +161,8 @@ Implemented today: - Provider profiles record connection shapes without credentials or adapters (ADR-0038). Trusted approval records bind a future model-tool call to a session, workspace, operation, request digest, and settings revision, expire, - and are consumed once (ADR-0039). Neither enables a provider connection or a - model tool. + and are consumed once (ADR-0039). Provider profiles enable no connection; the + command tool is the only model tool that consumes an approval record. - The `workspace_run_command` model tool (ADR-0040) is offered only with live `model_tools`, `execute`, `read`, and `write`. Its first call records a pending approval and starts nothing; an approved exact call consumes the @@ -173,12 +177,12 @@ Not implemented: - Apply or restore on other filesystems, workspace file deletion, ledger compaction, and standalone CLI checkpoint preparation. -- Model write, process, network, Git, or MCP tools; per-call tool approval; - and live provider tool-call qualification. -- Model-callable process execution, a network destination allowlist, Git, - MCP, runtime skills, memories, desktop/UI panels, compaction, or caches. - Nothing calls the unconfined process runner. -- Subscription/API-key provider profiles beyond the local LM Studio route. +- Model write, network, Git, and MCP tools; live provider tool-call + qualification; and streaming, discovery, and cancellation in a live provider. +- A run network destination allowlist, runtime skills, memories, desktop/UI + panels, compaction, and caches. Nothing calls the unconfined process runner. +- Provider adapters and subscription/API-key login; the recorded provider + profiles are configuration only. ## Resume steps @@ -550,12 +554,18 @@ on Windows, and trusted CLI commands as the first caller. See before calling the trusted runner. It uses fixed limits and no network or host services. See [ADR-0040](docs/adr/0040-gate-the-model-command-tool-with-approvals-and-the-trusted-runner.md). +- **C15 (this branch, version 0.25.0 qualification):** native end-to-end + acceptance for the model command tool. The real chat CLI, a mock provider, + two turns, an operator approval, and the trusted runner run one successful + confined command on Linux and Windows. Linux needs a delegated cgroup; + Windows needs a workspace container grant. The case fails, rather than + skips, when the host cannot provide them. Confinement correctness remains + the platform suites' responsibility. Next decisions, not yet scheduled: - a credential service, provider adapters, and subscription/API-key login; - model write, network, Git, and MCP tools; -- native successful-command qualification for the model tool; - registry credentials and development-server networking. ### Phase D: additional providers, streaming, and account lifecycle diff --git a/docs/development.md b/docs/development.md index 03f8a08..33afe7e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # Build and run the core prototype -OMGCode 0.17.0 is a developer CLI prototype with workspace permission +OMGCode 0.25.0 is a developer CLI prototype with workspace permission settings and bounded native file operations through trusted operator commands. It can send a text conversation to an explicitly selected local LM Studio model and save that conversation. It can read/list files, exclusively create new @@ -352,16 +352,20 @@ reason and a `withheld_tool_results` count. Text which resembles a command remains text. When the workspace enables `model_tools`, chat offers `workspace_read_file` and -`workspace_list_directory`. The model may make up to four requests in one turn. -Each call is rechecked against live settings and stays inside the workspace. -Results return to the model as source-labelled user messages. The configured -LM Studio token is removed from each result before it is recorded or sent. A -tool call that contains the token is refused with a `provider` error before it -is recorded, because editing its arguments could change the requested path. -Saved tool results are sent again only while the live `model_tools` and `read` -preferences both allow it. There is no per-call approval prompt. The output reports -`model_tools.mode` as `enabled`, with the workspace ID, rounds, call count, -tool bytes, and withheld count. `reply.finish_reason` is `length` when the token +`workspace_list_directory`. When `execute`, `read`, and `write` also allow it, +it offers the approval-gated `workspace_run_command`. The model may make up to +four requests in one turn. Each read/list call is rechecked against live +settings and stays inside the workspace. Results return to the model as +source-labelled user messages. The configured LM Studio token is removed from +each result before it is recorded or sent. A tool call that contains the token +is refused with a `provider` error before it is recorded, because editing its +arguments could change the requested path. Saved tool results are sent again +only while the live `model_tools` and `read` preferences both allow it. Chat +prompts for no approval: a command call first records a pending approval and +returns `approval_required`; the operator runs `approvals approve ` between +turns, and a second identical call consumes it and calls the trusted runner. +The output reports `model_tools.mode` as `enabled`, with the workspace ID, +rounds, call count, tool bytes, and withheld count. `reply.finish_reason` is `length` when the token limit cut the final reply short; the turn is still recorded as complete. A refused or invalid call ends the turn with a `permission`, `tool_call`, or `tool_limit` error, recorded in the journal. From 15c9de38dcf7a1ed6e900c3e8c3096337e8cc955 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 11:13:16 +0000 Subject: [PATCH 13/17] chore: ignore Serena workspace metadata Co-Authored-By: Claude Code --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index c3ec7d2..56de40e 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,9 @@ target # rustc will dump stack traces when hitting an internal compiler error to PWD rustc-ice-*.txt +# Serena local workspace metadata +.serena/ + # RustRover # JetBrains specific template is maintained in a separate JetBrains.gitignore that can # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore From 74aa8f2a9d0ed14ae281296512e6eeb4cdcd921e Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 12:28:23 +0000 Subject: [PATCH 14/17] test: bound the disk limit run before the CLI deadline The Windows CI runner can spend more than the default ten-second CLI test deadline copying 32 MiB and waiting for the one-second disk sampler. Give the run an explicit 45-second deadline and the CLI 60 seconds, so a missed limit records a bounded deadline instead of leaving a pending run when the harness stops the CLI. The limit assertions are unchanged. Co-Authored-By: Claude Code --- IMPLEMENTATION_PLAN.md | 10 +++++++--- crates/omgcode-cli/tests/run_workflow.rs | 15 +++++++++++++-- crates/omgcode-cli/tests/support/run_scene.rs | 3 ++- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 1422b83..fac2a1d 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -602,9 +602,13 @@ release readiness remain separate gates. [testing standards](docs/testing-standards.md#isolation-and-concurrency) covers the CLI suites. `omgcode-core`'s `file_broker` FIFO test still spawns one child beside in-process stores; it did not fail in 60 parallel runs and is not gated. -- Local Windows all-target runs intermittently timed out in pre-existing - multi-fixture provider tests under host load. The tests pass individually and - CI passed on `987a5aa`; recheck on a clean host rather than weakening a test. +- Windows runs under host load can outlast the default 10-second CLI test + deadline. The disk-limit case now gives the run an explicit 45-second + deadline and the CLI 60 seconds, so a missed sampler ends as a recorded + deadline instead of a killed CLI with a pending run. The pre-existing + multi-fixture provider tests also timed out locally under host load; they + pass individually and passed CI on `987a5aa`. Recheck timeouts on a clean + host rather than weakening an assertion. - `.serena/` is untracked and unrelated. Do not commit or delete it without deciding what it is. - The turn runtime is library/test infrastructure until a provider adapter and diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index d1aac3b..6ee22ec 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -880,8 +880,19 @@ fn a_disk_limit_ends_the_run_and_is_recorded() { let script = "cp growth-source.bin growth.bin; while :; do :; done"; #[cfg(windows)] let script = "copy /b growth-source.bin growth.bin >nul & for /l %i in (1,0,2) do @rem"; - let options = ["--max-disk-mib", "16", "--max-memory-mib", "512"]; - let run = run_json(&scene.run("system", &options, &shell(script))); + let options = [ + "--max-disk-mib", + "16", + "--max-memory-mib", + "512", + // Copying 32 MiB and sampling once a second can outlast the normal + // 10-second CLI deadline on a loaded runner. Bound the run itself so + // a missed disk limit still records a deadline instead of leaving the + // run pending when the harness stops the CLI. + "--timeout-secs", + "45", + ]; + let run = run_json(&scene.run_for("system", &options, &shell(script), Duration::from_secs(60))); assert_eq!( run["start"]["limits"]["max_disk_bytes"], 16u64 * 1024 * 1024 diff --git a/crates/omgcode-cli/tests/support/run_scene.rs b/crates/omgcode-cli/tests/support/run_scene.rs index df778d3..2e23cc7 100644 --- a/crates/omgcode-cli/tests/support/run_scene.rs +++ b/crates/omgcode-cli/tests/support/run_scene.rs @@ -239,7 +239,8 @@ impl Scene { self.run_for(profile, options, command, super::CLI_DEADLINE) } - /// Run a command with a longer CLI deadline, for real builds. + /// Run a command with a longer CLI deadline, for real builds and + /// I/O-heavy cases. pub(crate) fn run_for( &self, profile: &str, From b24ca28eeac2e3bd3870023f26f61d8d2bc8204b Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 12:32:57 +0000 Subject: [PATCH 15/17] test: create disk growth directly on Windows The Windows CI runner did not observe growth from a 32 MiB copy before the bounded deadline. Use fsutil to set the logical length directly, which the sampler checks independently of allocated bytes, and include the run record in assertion failures. Co-Authored-By: Claude Code --- crates/omgcode-cli/tests/run_workflow.rs | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index 6ee22ec..dad8c25 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -871,21 +871,25 @@ fn a_tree_limit_ends_the_run_and_is_recorded() { fn a_disk_limit_ends_the_run_and_is_recorded() { let scene = Scene::new(); assert_success(&scene.add_profile("system", &[])); - // The source exists before the run, so the baseline counts it. Copying it - // inside the writable workspace adds bytes the disk limit must see. Both - // commands then wait to be stopped. + // The source exists before the run, so the baseline counts it. Growing the + // writable workspace adds bytes the disk limit must see; each command then + // waits to be stopped. + #[cfg(target_os = "linux")] let source = scene.workspace.join("growth-source.bin"); + #[cfg(target_os = "linux")] fs::write(&source, vec![0u8; 32 * 1024 * 1024]).expect("growth source"); #[cfg(target_os = "linux")] let script = "cp growth-source.bin growth.bin; while :; do :; done"; + // `fsutil` sets the logical length directly. A 32 MiB copy was slow or + // failed on the Windows CI runner before the sampler saw growth. #[cfg(windows)] - let script = "copy /b growth-source.bin growth.bin >nul & for /l %i in (1,0,2) do @rem"; + let script = "fsutil file createnew growth.bin 33554432 >nul & for /l %i in (1,0,2) do @rem"; let options = [ "--max-disk-mib", "16", "--max-memory-mib", "512", - // Copying 32 MiB and sampling once a second can outlast the normal + // Creating 32 MiB and sampling once a second can outlast the normal // 10-second CLI deadline on a loaded runner. Bound the run itself so // a missed disk limit still records a deadline instead of leaving the // run pending when the harness stops the CLI. @@ -895,10 +899,11 @@ fn a_disk_limit_ends_the_run_and_is_recorded() { let run = run_json(&scene.run_for("system", &options, &shell(script), Duration::from_secs(60))); assert_eq!( run["start"]["limits"]["max_disk_bytes"], - 16u64 * 1024 * 1024 + 16u64 * 1024 * 1024, + "{run}" ); - assert_eq!(run["finish"]["result"]["kind"], "limit_exceeded"); - assert_eq!(run["finish"]["result"]["limit"], "disk"); + assert_eq!(run["finish"]["result"]["kind"], "limit_exceeded", "{run}"); + assert_eq!(run["finish"]["result"]["limit"], "disk", "{run}"); assert!( run["finish"]["usage"]["peak_disk_bytes"] .as_u64() From e12fcf5b2dc4c4e63247a5079a5df00f7db0b433 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 12:40:34 +0000 Subject: [PATCH 16/17] test: build disk growth with cmd built-ins The AppContainer cannot use fsutil, PowerShell, or a copied host file on the CI runner; each failed with access denied, so growth stayed at zero. Create and double files inside the container with echo and copy, which only need the workspace grant, until the length ceiling is crossed. Co-Authored-By: Claude Code --- crates/omgcode-cli/tests/run_workflow.rs | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index dad8c25..338cf58 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -879,11 +879,22 @@ fn a_disk_limit_ends_the_run_and_is_recorded() { #[cfg(target_os = "linux")] fs::write(&source, vec![0u8; 32 * 1024 * 1024]).expect("growth source"); #[cfg(target_os = "linux")] - let script = "cp growth-source.bin growth.bin; while :; do :; done"; - // `fsutil` sets the logical length directly. A 32 MiB copy was slow or - // failed on the Windows CI runner before the sampler saw growth. + let script = "cp growth-source.bin growth.bin; while :; do :; done".to_owned(); + // Build the growth with `cmd` built-ins and files the container creates. + // External tools need grants the CI container lacks, and it could not read + // a host-created source. Doubling a small file passes 16 MiB quickly. #[cfg(windows)] - let script = "fsutil file createnew growth.bin 33554432 >nul & for /l %i in (1,0,2) do @rem"; + let script = { + let mut script = String::from("echo x>g0"); + for step in 1..=25 { + script.push_str(&format!( + "& copy /b g{previous}+g{previous} g{step} >nul", + previous = step - 1 + )); + } + script.push_str("& for /l %i in (1,0,2) do @rem"); + script + }; let options = [ "--max-disk-mib", "16", @@ -896,7 +907,8 @@ fn a_disk_limit_ends_the_run_and_is_recorded() { "--timeout-secs", "45", ]; - let run = run_json(&scene.run_for("system", &options, &shell(script), Duration::from_secs(60))); + let run = + run_json(&scene.run_for("system", &options, &shell(&script), Duration::from_secs(60))); assert_eq!( run["start"]["limits"]["max_disk_bytes"], 16u64 * 1024 * 1024, From 8a0cf5e95d436fecf816e87df2a487bb17646e0c Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sat, 14 Nov 2026 12:47:20 +0000 Subject: [PATCH 17/17] test: append disk growth with type inside the container The CI AppContainer denied copy, fsutil, and PowerShell, leaving only the small echo file. Create a 7 KiB chunk and append it with type inside a grouped loop; both operations use only container-created files and the workspace grant. The limit is crossed in a few seconds, and the sampler stops the tree. Co-Authored-By: Claude Code --- crates/omgcode-cli/tests/run_workflow.rs | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/crates/omgcode-cli/tests/run_workflow.rs b/crates/omgcode-cli/tests/run_workflow.rs index 338cf58..419c562 100644 --- a/crates/omgcode-cli/tests/run_workflow.rs +++ b/crates/omgcode-cli/tests/run_workflow.rs @@ -881,19 +881,15 @@ fn a_disk_limit_ends_the_run_and_is_recorded() { #[cfg(target_os = "linux")] let script = "cp growth-source.bin growth.bin; while :; do :; done".to_owned(); // Build the growth with `cmd` built-ins and files the container creates. - // External tools need grants the CI container lacks, and it could not read - // a host-created source. Doubling a small file passes 16 MiB quickly. + // External tools and `copy` were denied in the CI container, but `echo` + // creation and `type` of a container-created file work. Append a 7 KiB + // chunk enough times to pass 16 MiB. #[cfg(windows)] let script = { - let mut script = String::from("echo x>g0"); - for step in 1..=25 { - script.push_str(&format!( - "& copy /b g{previous}+g{previous} g{step} >nul", - previous = step - 1 - )); - } - script.push_str("& for /l %i in (1,0,2) do @rem"); - script + let chunk = "x".repeat(7000); + format!( + "echo {chunk}>chunk & (for /l %i in (1,1,2500) do @type chunk>>growth.bin) & for /l %i in (1,0,2) do @rem" + ) }; let options = [ "--max-disk-mib",