feat(stdlib): add explicitly granted env API
This commit is contained in:
1 parent
ae69391bc0
commit
9922bfae98
17 files changed
+322
-15
No files matched your search
@@ -24,6 +24,8 @@ pub struct SandboxSettings {
|
||||
pub allow_write: Vec<String>,
|
||||
/// Network grants (IP literals, ADR-0034).
|
||||
pub allow_net: Vec<String>,
|
||||
/// Environment variable grants (ADR-0043).
|
||||
pub allow_env: Vec<String>,
|
||||
/// Foreign execution grant.
|
||||
pub allow_foreign: bool,
|
||||
/// Plugin grants.
|
||||
@@ -74,6 +76,7 @@ impl SandboxSettings {
|
||||
|| !self.allow_read.is_empty()
|
||||
|| !self.allow_net.is_empty()
|
||||
|| !self.allow_write.is_empty()
|
||||
|| !self.allow_env.is_empty()
|
||||
|| !self.allow_plugin.is_empty()
|
||||
|| !self.plugins.is_empty()
|
||||
|| self.trust_native_plugin
|
||||
@@ -82,8 +85,8 @@ impl SandboxSettings {
|
||||
if requested {
|
||||
return Err(
|
||||
"strict mode currently supports pure Marqdo and native Math only; \
|
||||
--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/\
|
||||
--trust-native-plugin/--kernel/--trace-file are rejected. Use \
|
||||
--allow-read/--allow-write/--allow-env/--allow-foreign/--allow-plugin/\
|
||||
--plugin/--trust-native-plugin/--kernel/--trace-file are rejected. Use \
|
||||
--mode project for those capabilities."
|
||||
.to_string(),
|
||||
);
|
||||
@@ -99,6 +102,7 @@ impl SandboxSettings {
|
||||
if !self.allow_read.is_empty()
|
||||
|| !self.allow_net.is_empty()
|
||||
|| !self.allow_write.is_empty()
|
||||
|| !self.allow_env.is_empty()
|
||||
|| self.allow_foreign
|
||||
|| !self.allow_plugin.is_empty()
|
||||
{
|
||||
@@ -119,6 +123,9 @@ impl SandboxSettings {
|
||||
for host in &self.allow_net {
|
||||
capabilities = capabilities.allow_net(host.clone());
|
||||
}
|
||||
for name in &self.allow_env {
|
||||
capabilities = capabilities.allow_env(name.clone());
|
||||
}
|
||||
if self.allow_foreign {
|
||||
capabilities = capabilities.allow_foreign();
|
||||
}
|
||||
|
||||
@@ -92,6 +92,9 @@ struct SandboxArgs {
|
||||
/// Grant write access to a project-relative glob (repeatable).
|
||||
#[arg(long = "allow-write", value_name = "GLOB")]
|
||||
allow_write: Vec<String>,
|
||||
/// Grant read access to an environment variable (repeatable, ADR-0043).
|
||||
#[arg(long = "allow-env", value_name = "NAME")]
|
||||
allow_env: Vec<String>,
|
||||
/// Grant explicit foreign kernel execution.
|
||||
#[arg(long = "allow-foreign")]
|
||||
allow_foreign: bool,
|
||||
@@ -143,6 +146,7 @@ impl SandboxArgs {
|
||||
allow_read: self.allow_read.clone(),
|
||||
allow_net: self.allow_net.clone(),
|
||||
allow_write: self.allow_write.clone(),
|
||||
allow_env: self.allow_env.clone(),
|
||||
allow_foreign: self.allow_foreign,
|
||||
allow_plugin: self.allow_plugin.clone(),
|
||||
fuel: self.fuel,
|
||||
|
||||
@@ -38,6 +38,7 @@ struct TestFile {
|
||||
stdin: &'static str,
|
||||
stdout: &'static str,
|
||||
args: &'static [&'static str],
|
||||
env: &'static [(&'static str, &'static str)],
|
||||
}
|
||||
|
||||
fn product_tests() -> Vec<TestFile> {
|
||||
@@ -52,6 +53,7 @@ fn product_tests() -> Vec<TestFile> {
|
||||
stdin: "",
|
||||
stdout: "",
|
||||
args: &[],
|
||||
env: &[],
|
||||
};
|
||||
}
|
||||
let name = path.file_name().unwrap().to_string_lossy().to_string();
|
||||
@@ -72,6 +74,18 @@ fn product_tests() -> Vec<TestFile> {
|
||||
"--allow-write",
|
||||
"out/**",
|
||||
][..]
|
||||
} else if name == "env.mq.md" {
|
||||
&[
|
||||
"--allow-env",
|
||||
"MARQDO_TEST_ENV",
|
||||
"--allow-env",
|
||||
"MARQDO_MISSING_ENV",
|
||||
][..]
|
||||
} else {
|
||||
&[][..]
|
||||
};
|
||||
let env = if name == "env.mq.md" {
|
||||
&[("MARQDO_TEST_ENV", "env-value")][..]
|
||||
} else {
|
||||
&[][..]
|
||||
};
|
||||
@@ -80,6 +94,7 @@ fn product_tests() -> Vec<TestFile> {
|
||||
stdin,
|
||||
stdout,
|
||||
args,
|
||||
env,
|
||||
}
|
||||
})
|
||||
.filter(|file| !file.name.is_empty())
|
||||
@@ -99,6 +114,7 @@ fn run_product_test(file: &TestFile) -> serde_json::Value {
|
||||
.args(["--json"])
|
||||
.current_dir(stdlib_dir())
|
||||
.env("MARQDO_STDLIB_DIR", stdlib_dir())
|
||||
.envs(file.env.iter().copied())
|
||||
.stdin(Stdio::piped())
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
@@ -132,6 +148,7 @@ fn every_public_stdlib_module_has_a_product_test() {
|
||||
"csv.mq.md",
|
||||
"datetime.mq.md",
|
||||
"demo.mq.md",
|
||||
"env.mq.md",
|
||||
"format.mq.md",
|
||||
"fs.mq.md",
|
||||
"http.mq.md",
|
||||
@@ -310,6 +327,23 @@ fn clock_test_reports_project_mode_unix_millis() {
|
||||
assert_eq!(items[2]["value"], true);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn env_test_reads_only_granted_names() {
|
||||
let report = run_product_test(
|
||||
product_tests()
|
||||
.iter()
|
||||
.find(|file| file.name == "env.mq.md")
|
||||
.expect("env test"),
|
||||
);
|
||||
let items = report["value"]["items"].as_array().expect("list");
|
||||
assert_eq!(items[0]["value"], true);
|
||||
assert_eq!(items[1]["value"], true);
|
||||
assert_eq!(items[2]["value"], true);
|
||||
assert_eq!(items[3]["value"], "env-value");
|
||||
assert_eq!(items[4]["value"], false);
|
||||
assert_eq!(items[5]["value"], "env.not_found");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn format_test_pins_value_semantics_and_handle_observation() {
|
||||
let report = run_product_test(
|
||||
|
||||
@@ -317,6 +317,8 @@ pub struct Capabilities {
|
||||
pub fs_write: Vec<String>,
|
||||
/// Allowed network hosts (empty = no network).
|
||||
pub net_hosts: Vec<String>,
|
||||
/// Allowed environment variable names (empty = no environment).
|
||||
pub env: Vec<String>,
|
||||
/// May spawn processes (foreign kernels).
|
||||
pub process: bool,
|
||||
/// May run foreign kernels (Python/Node).
|
||||
@@ -336,6 +338,7 @@ impl Capabilities {
|
||||
fs_read: Vec::new(),
|
||||
fs_write: Vec::new(),
|
||||
net_hosts: Vec::new(),
|
||||
env: Vec::new(),
|
||||
process: false,
|
||||
foreign: false,
|
||||
plugins: Vec::new(),
|
||||
@@ -361,6 +364,25 @@ impl Capabilities {
|
||||
self
|
||||
}
|
||||
|
||||
/// Grant read access to one environment variable name (ADR-0043).
|
||||
pub fn allow_env(mut self, name: impl Into<String>) -> Self {
|
||||
self.env.push(name.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Check an environment variable grant. Names are exact, not globs.
|
||||
pub fn check_env(&self, name: &str, span: Option<Span>) -> Result<(), RuntimeError> {
|
||||
if self.env.iter().any(|allowed| allowed == name) {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(denied(
|
||||
span,
|
||||
format!("environment variable `{name}` was not granted"),
|
||||
format!("grant it with --allow-env {name}"),
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
/// Grant foreign kernel execution.
|
||||
pub fn allow_foreign(mut self) -> Self {
|
||||
self.foreign = true;
|
||||
|
||||
@@ -1127,6 +1127,58 @@ impl Host for StdHost {
|
||||
"resource operations accept only Text path arguments",
|
||||
));
|
||||
}
|
||||
if operation == "env.get" {
|
||||
if args.len() != 1 {
|
||||
return Err(RuntimeError::new(
|
||||
ErrorCategory::Arity,
|
||||
ctx.span,
|
||||
format!(
|
||||
"resource operation `env.get` expects 1 argument, got {}",
|
||||
args.len()
|
||||
),
|
||||
));
|
||||
}
|
||||
let value_type = args[0].type_name();
|
||||
let Value::Text(name) = args[0].clone() else {
|
||||
return Err(RuntimeError::type_error(
|
||||
ctx.span,
|
||||
format!("resource operation `env.get` expects a Text name, got {value_type}"),
|
||||
));
|
||||
};
|
||||
self.capabilities.check_env(&name, ctx.span)?;
|
||||
let mut map = BTreeMap::new();
|
||||
match std::env::var(&name) {
|
||||
Ok(value) => {
|
||||
map.insert("ok".to_string(), Value::Bool(true));
|
||||
map.insert("value".to_string(), Value::text(value));
|
||||
}
|
||||
Err(std::env::VarError::NotPresent) => {
|
||||
map.insert("ok".to_string(), Value::Bool(false));
|
||||
map.insert("code".to_string(), Value::text("env.not_found"));
|
||||
map.insert(
|
||||
"message".to_string(),
|
||||
Value::text(format!("environment variable `{name}` is not set")),
|
||||
);
|
||||
}
|
||||
Err(std::env::VarError::NotUnicode(_)) => {
|
||||
map.insert("ok".to_string(), Value::Bool(false));
|
||||
map.insert("code".to_string(), Value::text("env.not_unicode"));
|
||||
map.insert(
|
||||
"message".to_string(),
|
||||
Value::text(format!("environment variable `{name}` is not valid UTF-8")),
|
||||
);
|
||||
}
|
||||
}
|
||||
self.record_semantic(
|
||||
"resource.request",
|
||||
None,
|
||||
Some(&ctx.module_id),
|
||||
ctx.span,
|
||||
Some("op=env.get"),
|
||||
);
|
||||
self.record_resource_effect("resource.request", ctx, started, "env.get");
|
||||
return Ok(Value::Map(map));
|
||||
}
|
||||
if operation == "clock.now" {
|
||||
if !args.is_empty() {
|
||||
return Err(RuntimeError::new(
|
||||
|
||||
@@ -641,3 +641,44 @@ fn clock_now_is_project_only_and_returns_unix_millis() {
|
||||
.unwrap_err();
|
||||
assert_eq!(error.category, ErrorCategory::Arity);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn env_get_requires_an_exact_grant_and_reports_missing_names() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let ctx = context();
|
||||
let mut denied = StdHost::new(SandboxMode::Project, Capabilities::project(), dir.path());
|
||||
let error = denied
|
||||
.resource_request("env.get", vec![Value::text("PATH")], &ctx)
|
||||
.unwrap_err();
|
||||
assert_eq!(error.category, ErrorCategory::PermissionDenied);
|
||||
|
||||
let mut pure = StdHost::new(SandboxMode::Pure, Capabilities::pure(), dir.path());
|
||||
let error = pure
|
||||
.resource_request("env.get", vec![Value::text("PATH")], &ctx)
|
||||
.unwrap_err();
|
||||
assert_eq!(error.category, ErrorCategory::PermissionDenied);
|
||||
|
||||
let capabilities = Capabilities::project()
|
||||
.allow_env("PATH")
|
||||
.allow_env("MARQDO_TEST_MISSING_ENV");
|
||||
let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path());
|
||||
let present = host
|
||||
.resource_request("env.get", vec![Value::text("PATH")], &ctx)
|
||||
.unwrap();
|
||||
assert_eq!(field(&present, "ok"), &Value::Bool(true));
|
||||
|
||||
let missing = host
|
||||
.resource_request(
|
||||
"env.get",
|
||||
vec![Value::text("MARQDO_TEST_MISSING_ENV")],
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(field(&missing, "ok"), &Value::Bool(false));
|
||||
assert_eq!(field(&missing, "code"), &Value::text("env.not_found"));
|
||||
|
||||
let error = host
|
||||
.resource_request("env.get", Vec::new(), &ctx)
|
||||
.unwrap_err();
|
||||
assert_eq!(error.category, ErrorCategory::Arity);
|
||||
}
|
||||
+7
-6
@@ -58,7 +58,7 @@ byte-identical).
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked PASS
|
||||
474 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
|
||||
476 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
|
||||
```
|
||||
|
||||
The documentation and test migration is local work; re-run this block after it
|
||||
@@ -203,11 +203,12 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
`删除`/`重命名` over `resource.request` (ADR-0041); `data/json`/`data/csv`
|
||||
provide recursive JSON and quoted single-row CSV product parsers; `path` and a
|
||||
`regex` subset are pure `.mq.md`; `datetime` is pure UTC ISO-8601 and
|
||||
`clock.现在` reads `clock.now` in project mode (ADR-0042). Append/seek/watch,
|
||||
recursive walk, streaming JSON/CSV, a JSON depth bound, regex groups/
|
||||
alternation and `env`/`process` remain open.
|
||||
`clock.现在` reads `clock.now` in project mode (ADR-0042); `env.读取` reads
|
||||
only exact `--allow-env NAME` grants in project mode (ADR-0043). Append/seek/
|
||||
watch, recursive walk, streaming JSON/CSV, a JSON depth bound, regex groups/
|
||||
alternation and `process` remain open.
|
||||
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
|
||||
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`; explicit `std:` imports resolve only inside the bundle;
|
||||
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`/`env`; explicit `std:` imports resolve only inside the bundle;
|
||||
a SHA-256 digest over `*.mq.md` is verified before loading; Analysis records
|
||||
`project.stdlib`; a frozen-binary test asserts the CLI hash is unchanged after
|
||||
running a `std:io` project and that tampering is rejected. `打印/print` is
|
||||
@@ -233,7 +234,7 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
status/index links and SHA-pinned evidence; `crates/cli/tests/architecture_boundaries.rs`
|
||||
pins the workspace graph, `marqdo-runtime -> marqdo-host`, the bundled stdlib
|
||||
digest and the stdio/file/TCP endpoints; `crates/cli/tests/stdlib_product.rs`
|
||||
runs every public stdlib module (`clock/console/csv/datetime/demo/format/fs/http/io/json/path/regex/stream/table/text/utf8`)
|
||||
runs every public stdlib module (`clock/console/csv/datetime/demo/env/format/fs/http/io/json/path/regex/stream/table/text/utf8`)
|
||||
through `std:` imports over `stdlib/tests/*.mq.md`. `tools/pack-stdlib.py`
|
||||
now sorts `.mq.md` by the same relative path key as the CLI. Source/test baseline
|
||||
`0d40de7`; later docs-only commits keep code/test bytes identical. Evidence:
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# ADR-0043: Explicitly granted `env.get` resource operation
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Relates to: ADR-0041, ADR-0042
|
||||
Specs: `spec/security.md`, `spec/evaluation.md`
|
||||
Evidence: `docs/evidence/2026-11-21-env-product.md`
|
||||
|
||||
## Context
|
||||
|
||||
A product `std:env` module needs to read process environment variables. The
|
||||
environment is an ambient OS side channel that can contain secrets and
|
||||
credentials. Reading it through a wildcard path grant or by default would
|
||||
silently widen the capability surface; `env.list` would expose every variable
|
||||
without naming it.
|
||||
|
||||
## Decision
|
||||
|
||||
Add one operation to `resource.request`:
|
||||
|
||||
```text
|
||||
resource.request("env.get", [name]) -> {ok:true, value:Text}
|
||||
| {ok:false, code:"env.not_found"}
|
||||
| {ok:false, code:"env.not_unicode"}
|
||||
```
|
||||
|
||||
* Arguments: exactly one `Text` variable name. Non-Text or wrong arity is a
|
||||
fatal type/arity error.
|
||||
* Grants: a new `Capabilities::env: Vec<String>` with **exact name matching**
|
||||
(no glob). `--allow-env NAME` adds one grant; un-granted names return
|
||||
`permission.denied` before the OS is read.
|
||||
* The check happens before `std::env::var`. Project mode only; `pure` and
|
||||
`strict` refuse. No default grant.
|
||||
* Missing variables and non-UTF-8 variables are recoverable
|
||||
`env.not_found`/`env.not_unicode`, not fatal errors.
|
||||
* There is no `env.list`, `env.set`, process spawning or `std::env::set_var`
|
||||
in this decision. A future `env.list` would need a separate ADR because it
|
||||
changes the disclosure model.
|
||||
* `stdlib/env.mq.md` is a thin `.mq.md` facade: `读取` returns the Result and
|
||||
`存在` maps `env.not_found` to `{ok:true, value:false}`.
|
||||
|
||||
## Consequences
|
||||
|
||||
* The environment is readable only by exact, operator-supplied names in
|
||||
project mode.
|
||||
* The CLI gains `--allow-env NAME`; strict mode rejects it with exit 2.
|
||||
* `std:process` remains unsupported in this decision; process execution needs
|
||||
its own capability and OS-sandbox story.
|
||||
@@ -18,7 +18,7 @@ platform".
|
||||
| Dimension | Current state | Source |
|
||||
|---|---|---|
|
||||
| Implemented | Rust workspace `0.1.0`: Markdown/frontend/IR, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
|
||||
| Tested locally | `cargo test --workspace --locked`: **474 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
|
||||
| Tested locally | `cargo test --workspace --locked`: **476 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
|
||||
| Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` |
|
||||
| Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 |
|
||||
|
||||
@@ -94,6 +94,7 @@ review RFC, not a new crate per provider.
|
||||
| `std:regex` | `regex.匹配/搜索` with `^ $ . * + ? [...]` escapes | implemented subset; no groups/alternation | `stdlib_product` |
|
||||
| `std:datetime` | `datetime.格式化(毫秒)` / `datetime.解析(文本)`; UTC ISO-8601, pre-1970 supported | implemented (pure) | `stdlib_product` |
|
||||
| `std:clock` | `clock.现在()` -> `resource.request("clock.now", [])` | implemented (project mode; pure/strict denied) | `resource_streams`, `stdlib_product` |
|
||||
| `std:env` | `env.读取/存在` -> `resource.request("env.get", [name])`; exact `--allow-env` grant | implemented (project mode; no `env.list`) | `resource_streams`, `stdlib_product` |
|
||||
| file metadata / directory / rename / remove / mkdir | not part of the current Resource contract | **not implemented**; needs a separate Resource Operation ADR | — |
|
||||
| TCP | `resource.open("tcp", ip:port, ["read","write"])`; exact IP grant, 5 s timeout | implemented; no DNS/TLS/server socket/UDP | `tcp_endpoint`, `http_over_tcp` |
|
||||
| HTTP/1.1 | `stdlib/net/http.mq.md`: status/header/chunked-byte parse, request build | implemented over an already-authorized TCP stream; not a DNS/TLS client | `stdlib_http`, `http_over_tcp`, `stdlib_product` |
|
||||
@@ -125,7 +126,7 @@ that a phase is complete.
|
||||
| P1 | `crates/cli/src/commands.rs` and `crates/marqdo-host/src/host.rs` still mix multiple responsibilities | open refactor, behavior-preserving |
|
||||
| P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release |
|
||||
| P2 | No DNS, TLS, listener or UDP provider | open |
|
||||
| P2 | `std:path`, a regex subset, `std:datetime` and `std:clock` are implemented; no `std:env`, `std:process`, secure random or compression | open |
|
||||
| P2 | `std:path`, a regex subset, `std:datetime`, `std:clock` and `std:env` are implemented; no `std:process`, secure random or compression | open |
|
||||
| P2 | Memory limits: 16 MiB per region, 64 MiB per run | current budget, not a product limit |
|
||||
| P3 | No concurrency tasks, atomics or cancellable long-running scheduling | open; separate ADR |
|
||||
| P3 | No native optimizer/JIT or columnar numeric backend | open; benchmark-first |
|
||||
@@ -157,5 +158,6 @@ that a phase is complete.
|
||||
- [Stable-release implementation plan](../STABLE_RELEASE_IMPLEMENTATION.md) — next-phase plan; not implemented behavior.
|
||||
- [ADR-0041: non-streaming resource operations](../adr/0041-resource-operation-fs.md) — accepted `resource.request` `fs.*` contract.
|
||||
- [ADR-0042: `clock.now` resource operation](../adr/0042-clock-resource-operation.md) — accepted project-mode Unix-millis clock.
|
||||
- [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants.
|
||||
- [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input.
|
||||
- [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration.
|
||||
@@ -47,6 +47,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and
|
||||
| Stdio stdin/stderr plus stdlib stream/console APIs | [0040](../adr/0040-stdio-stdin-stderr-and-stdlib-streams.md) | Accepted (stdin read, separate stdout/stderr, product stdlib) |
|
||||
| Non-streaming `resource.request` `fs.*` operations | [0041](../adr/0041-resource-operation-fs.md) | Accepted (project mode, grant-checked, recoverable fs Result) |
|
||||
| `clock.now` resource operation | [0042](../adr/0042-clock-resource-operation.md) | Accepted (project mode, Unix millis) |
|
||||
| `env.get` resource operation | [0043](../adr/0043-env-resource-operation.md) | Accepted (exact-name project grant) |
|
||||
| Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication |
|
||||
|
||||
## Evidence and status
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Evidence: `std:env` and the `env.get` grant
|
||||
|
||||
Date: 2026-11-21 (Asia/Shanghai)
|
||||
Source baseline: `ae69391bc0e51e0b87f3ba15a3679111c40a1231`
|
||||
Repository: `marqdo-cli`
|
||||
Decision record: [ADR-0043](../adr/0043-env-resource-operation.md)
|
||||
RFC item: P2 environment product API
|
||||
|
||||
## Implemented
|
||||
|
||||
`resource.request("env.get", [name])` is a project-mode operation:
|
||||
|
||||
- exactly one Text name; wrong arity/type is fatal;
|
||||
- `Capabilities::env` is an exact-name list; `--allow-env NAME` adds one
|
||||
grant; un-granted names return `permission.denied` before `std::env::var`;
|
||||
- missing names are recoverable `env.not_found`; non-UTF-8 values are
|
||||
`env.not_unicode`;
|
||||
- no `env.list`, `env.set` or process execution.
|
||||
|
||||
`stdlib/env.mq.md` is a thin `.mq.md` facade: `读取` returns the Result and
|
||||
`存在` maps `env.not_found` to `{ok:true, value:false}`.
|
||||
|
||||
## Tests
|
||||
|
||||
`stdlib/tests/env.mq.md` runs through `std:env` with
|
||||
`--allow-env MARQDO_TEST_ENV --allow-env MARQDO_MISSING_ENV`; the harness sets
|
||||
`MARQDO_TEST_ENV=env-value`. `crates/marqdo-host/tests/resource_streams.rs`
|
||||
pins exact grants, pure-mode refusal, `env.not_found` and arity.
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace 476 passed, 0 failed, 2 ignored
|
||||
cargo test -p marqdo-host --test resource_streams 22 passed
|
||||
cargo test -p marqdo-cli --test stdlib_product 13 passed
|
||||
python3 tools/pack-stdlib.py PASS
|
||||
```
|
||||
|
||||
## Not covered
|
||||
|
||||
No environment enumeration, mutation, expansion, per-call delegation or
|
||||
process execution. `std:process` remains open and needs its own ADR and OS
|
||||
sandbox story.
|
||||
+5
-1
@@ -206,6 +206,7 @@ resource.request("fs.mkdir", [path]) -> {ok:true, value:None}
|
||||
resource.request("fs.remove", [path]) -> {ok:true, value:None}
|
||||
resource.request("fs.rename", [from, to]) -> {ok:true, value:None}
|
||||
resource.request("clock.now", []) -> {ok:true, value:UnixMillis}
|
||||
resource.request("env.get", [name]) -> {ok:true, value:Text}
|
||||
```
|
||||
|
||||
* Arguments are `Text` paths only. `Memory`/`Resource` values are rejected.
|
||||
@@ -227,6 +228,9 @@ resource.request("clock.now", []) -> {ok:true, value:UnixMillis}
|
||||
* `clock.now` takes no arguments and returns UTC Unix milliseconds. It is
|
||||
project-mode only like `fs.*`; a clock before the epoch is fatal host error
|
||||
(ADR-0042).
|
||||
* `env.get` takes one exact variable name and requires an `--allow-env NAME`
|
||||
grant; un-granted names are `permission.denied`, missing names are recoverable
|
||||
`env.not_found` and non-UTF-8 values are `env.not_unicode` (ADR-0043).
|
||||
|
||||
## 4. Errors
|
||||
|
||||
@@ -322,7 +326,7 @@ host boundary. Names are stable; adding one requires a spec update.
|
||||
| `resource.read` | `(handle, memory: Memory, offset: Int, max_bytes: Int) -> Result` | bounded chunk read into Memory; `{count,eof}` |
|
||||
| `resource.write` | `(handle, memory: Memory, offset: Int, length: Int) -> Result` | bounded byte write; `{count}` |
|
||||
| `resource.close` | `(handle) -> Result` | releases the host slot |
|
||||
| `resource.request` | `(operation: Text, arguments: List) -> Result` | non-streaming `fs.*` operations (ADR-0041) and `clock.now` (ADR-0042); project-mode and grant-checked |
|
||||
| `resource.request` | `(operation: Text, arguments: List) -> Result` | non-streaming `fs.*` operations (ADR-0041) `clock.now` (ADR-0042) and `env.get` (ADR-0043); project-mode and grant-checked |
|
||||
| `math.parse/eval/substitute` | see `spec/math.md` | P5; `math.simplify`/`math.differentiate` are declared but return `math.unsupported` in this build |
|
||||
| `foreign.run/call` | see `spec/foreign.md` | P5, capability-gated |
|
||||
| `fs.read/write` | see `spec/security.md` | capability-gated |
|
||||
|
||||
+11
-3
@@ -27,8 +27,8 @@ Normative implementation:
|
||||
| Mode | Intended guarantee | Actual status in this build |
|
||||
|---|---|---|
|
||||
| `pure` | No external I/O; memory computation and budgets only. | **Enforced.** `Capabilities::pure()` = `console`, `math` only; every FS/foreign/plugin grant flag makes the CLI exit 2 with "pure mode prohibits external I/O grants". |
|
||||
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-foreign`, `--allow-plugin` add grants. `resource.open` supports stdin read, separate stdout/stderr write, granted project-file read/write (ADR-0025/0026/0040), granted in-process provider kinds (ADR-0033) and granted IP-literal TCP streams (ADR-0034); process/device remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation; in-process providers are trusted, not sandboxed. |
|
||||
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `resource.open` is **refused** in strict except for the existing `stdio/stdout` console channel (console grant); stdin/stderr, file/TCP/provider/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030/0034/0040). `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console, native Math and the read-only bundled stdlib (published at `/run/marqdo-stdlib` for the Compat-C print chain); `--allow-read/--allow-write/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
|
||||
| `project` | Operator-approved project resources under `CapabilityHost` + bounded resources. | **Enforced for the implemented operations.** Defaults equal `pure`; `--allow-read`, `--allow-write`, `--allow-net`, `--allow-env`, `--allow-foreign`, `--allow-plugin` add grants. `resource.open` supports stdin read, separate stdout/stderr write, granted project-file read/write (ADR-0025/0026/0040), granted in-process provider kinds (ADR-0033) and granted IP-literal TCP streams (ADR-0034); process/device remain unsupported. Sandboxing is cooperative (in-process checks), not OS isolation; in-process providers are trusted, not sandboxed. |
|
||||
| `strict` | Untrusted documents under real OS isolation. | **Linux: enforced when the runtime probe passes (ADR-0021).** `resource.open` is **refused** in strict except for the existing `stdio/stdout` console channel (console grant); stdin/stderr, file/TCP/provider/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030/0034/0040). `PlatformCapabilities::detect()` runs a real Bubblewrap smoke test; success reports `Available { mechanism }`, failure reports `Unavailable { reason }`. Strict L1 supports the interpreter, console, native Math and the read-only bundled stdlib (published at `/run/marqdo-stdlib` for the Compat-C print chain); `--allow-read/--allow-write/--allow-net/--allow-env/--allow-foreign/--allow-plugin/--plugin/--trust-native-plugin/--kernel/--trace-file` are rejected with exit 2. macOS/Windows and Linux hosts without the mechanisms remain `Unavailable`; there is **no fallback** to an unrestricted process. |
|
||||
|
||||
`marqdo inspect <file> --platform` prints the detection report, for example:
|
||||
|
||||
@@ -60,6 +60,7 @@ set for one run:
|
||||
| `fs_read: Vec<String>` | empty | `fs.read` and project `resource.open("file", path, ["read"])` |
|
||||
| `fs_write: Vec<String>` | empty | `fs.write` and project `resource.open("file", path, ["write"])` |
|
||||
| `net_hosts: Vec<String>` | empty | exact IP-literal grants for `resource.open("tcp", "<ip>:<port>", ["read","write"])`; DNS is not resolved; `--allow-net <IP>` adds a grant (ADR-0034) |
|
||||
| `env: Vec<String>` | empty | exact-name grants for `resource.request("env.get", [name])`; no glob and no `env.list`; `--allow-env <NAME>` adds a grant (ADR-0043) |
|
||||
| `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` |
|
||||
| `foreign: bool` | `false` | foreign kernels |
|
||||
| `plugins: Vec<String>` | empty | `plugin.invoke` and `StdHost::load_plugin` |
|
||||
@@ -76,13 +77,17 @@ Requests versus grants:
|
||||
* CLI grant flags (`crates/cli/src/main.rs::SandboxArgs`):
|
||||
* `--allow-read <GLOB>` and `--allow-write <GLOB>` (repeatable, project mode
|
||||
only);
|
||||
* `--allow-net <IP>` (repeatable, exact IP literal, project mode only,
|
||||
ADR-0034);
|
||||
* `--allow-env <NAME>` (repeatable, exact environment variable name, project
|
||||
mode only, ADR-0043);
|
||||
* `--allow-foreign` (project mode only; sets `foreign = true` and
|
||||
`process = true`);
|
||||
* `--allow-plugin <PACKAGE-NAME>` (repeatable, project mode only; matches the
|
||||
manifest `plugin.name`, not the call namespace);
|
||||
* `--plugin <PATH>` (repeatable, loads a plugin after the trust check);
|
||||
* `--trust-native-plugin` (explicit in-process native trust decision).
|
||||
* There is no network grant flag and no plugin-worker flag in this build.
|
||||
* There is no plugin-worker flag in this build. Network and environment grants are exact and project-mode only.
|
||||
|
||||
### 2.1 Filesystem grants are project-relative globs
|
||||
|
||||
@@ -117,6 +122,9 @@ before reading. Full symlink/race hardening is an open P4 item.
|
||||
`HostOp` and the checks run immediately before the effect:
|
||||
|
||||
* `fs.read` → `capabilities.check_read(path)` then `ProjectFs::read`;
|
||||
* `resource.request("fs.*")` → `check_read`/`check_write` before path resolution;
|
||||
* `resource.request("env.get")` → `capabilities.check_env(name)` before
|
||||
`std::env::var`;
|
||||
* `fs.write` → `check_write` then `ProjectFs::write`;
|
||||
* math ops → `capabilities.math` (in `crates/marqdo-host/src/kernels.rs`);
|
||||
* foreign ops → `capabilities.check_foreign` (requires `foreign && process`);
|
||||
|
||||
@@ -15,6 +15,7 @@ module; a mismatch is a hard error.
|
||||
- `data/json.mq.md` — recursive JSON parser and formatter (recoverable Result)
|
||||
- `data/csv.mq.md` — quoted single-row CSV parser and formatter
|
||||
- `data/table.mq.md` — value-returning table select/filter/sort/append/set/join/group/GFM
|
||||
- `env.mq.md` — explicitly granted `env.get` names over `resource.request`
|
||||
- `datetime.mq.md` — UTC ISO-8601 format/parse over Unix milliseconds (pure)
|
||||
- `clock.mq.md` — project-mode `clock.now` over `resource.request`
|
||||
- `path.mq.md` — lexical join/basename/dirname/extension/normalize (no I/O)
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
## 读取
|
||||
|
||||
`(名称)`
|
||||
|
||||
读取一个显式授权的环境变量。名称是精确匹配,不支持 glob;未授权是
|
||||
`permission.denied`,未设置是 `env.not_found`,非 UTF-8 是
|
||||
`env.not_unicode`。
|
||||
|
||||
*resource.request("env.get", [名称])*
|
||||
|
||||
## 存在
|
||||
|
||||
`(名称)`
|
||||
|
||||
**结果 = 读取(名称)**
|
||||
|
||||
1. `结果.ok`
|
||||
|
||||
*{ok: true, value: true}*
|
||||
|
||||
1. `结果.code == "env.not_found"`
|
||||
|
||||
*{ok: true, value: false}*
|
||||
|
||||
*结果*
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "marqdo-stdlib",
|
||||
"version": "0.1.0",
|
||||
"digest": "sha256:030562dbce90a671f86fdef984620699925b39a302e2b68639ca752a94adde9c"
|
||||
"digest": "sha256:9ec0ba1a50db6bd8423ce3485ad5433fb3b8140032f61c6b4a6dd9bc97416f47"
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
import:
|
||||
env: "std:env"
|
||||
---
|
||||
|
||||
## main
|
||||
|
||||
**存在 = env.存在("MARQDO_TEST_ENV")**
|
||||
|
||||
**读取 = env.读取("MARQDO_TEST_ENV")**
|
||||
|
||||
**缺失 = env.读取("MARQDO_MISSING_ENV")**
|
||||
|
||||
*[存在.ok, 存在.value, 读取.ok, 读取.value, 缺失.ok, 缺失.code]*
|
||||
Reference in new issue
Block a user