feat(random): add explicitly granted OS entropy API

This commit is contained in:
Marqdo Agent committed 2026-11-21 10:25:11 +08:00
1 parent 6338fa10e9
commit ee0c6cc80a
20 files changed
+309 -15

No files matched your search

+7 -6
View File
@@ -58,7 +58,7 @@ byte-identical).
cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace --locked PASS
479 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests
481 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
@@ -207,11 +207,12 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
`clock.现在` reads `clock.now` in project mode (ADR-0042); `env.读取` reads
only exact `--allow-env NAME` grants in project mode (ADR-0043); `process.运行`
runs an exact `--allow-process PROGRAM` grant with 5 s timeout and 1 MiB caps
(ADR-0044, not an OS sandbox). File watch, binary offset reads, streaming
JSON/CSV, a JSON depth bound, regex groups/alternation, secure random and
compression remain open.
(ADR-0044, not an OS sandbox); `random.字节` reads explicitly granted
`random.bytes` entropy (ADR-0046). File watch, binary offset reads, streaming
JSON/CSV, a JSON depth bound, regex groups/alternation and compression remain
open.
- Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`/`env`/`process`; explicit `std:` imports resolve only inside the bundle;
`format`/`text`/`io`/`fs`/`data`/`path`/`regex`/`datetime`/`clock`/`env`/`process`/`random`; 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
@@ -237,7 +238,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/env/format/fs/http/io/json/path/process/regex/stream/table/text/utf8`)
runs every public stdlib module (`clock/console/csv/datetime/demo/env/format/fs/http/io/json/path/process/random/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,40 @@
# ADR-0046: Explicitly granted `random.bytes`
Status: **Accepted**
Date: 2026-11-21
Relates to: ADR-0041
Specs: `spec/security.md`, `spec/evaluation.md`
Evidence: `docs/evidence/2026-11-21-random-product.md`
## Context
The standard library had no product entropy API. Reading `/dev/urandom` or
using an OS RNG inside a Rust builtin would create an unaudited side channel
and would make `pure` mode non-deterministic without an explicit grant.
## Decision
Add one project-mode operation:
```text
resource.request("random.bytes", [count]) -> {ok:true, value:List<Int>}
```
* `count` is an `Int` in `1..=65536`; other values are fatal type errors.
* A new `Capabilities::random: bool` grant is required (`--allow-random`).
Un-granted calls are `permission.denied`; `pure`/`strict` refuse.
* Bytes come from the `getrandom` crate's OS entropy source; a source failure
is a fatal `host.error`.
* The operation returns a `List<Int>` of 0–255 values. It does not expose a
`Memory` handle or raw pointer.
* `stdlib/random.mq.md` exposes `字节(n)` and `整数(上限)`. `整数` combines
eight bytes and takes a modulus; it is **not** claimed to be unbiased
rejection sampling.
* No new builtin or `HostOp` is added.
## Consequences
* Entropy is opt-in per run and unavailable in pure/strict.
* The API is byte-list based, so callers can build their own distributions in
`.mq.md`; a cryptographically audited RNG API is out of scope.
* A future unbiased integer helper or secure token API needs its own ADR.
+4 -2
View File
@@ -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`: **478 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline | `docs/STATUS.md` §3 |
| Tested locally | `cargo test --workspace --locked`: **481 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 |
@@ -100,6 +100,7 @@ review RFC, not a new crate per provider.
| `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` |
| `std:process` | `process.运行(程序, 参数列表)` -> `resource.request("process.run", ...)`; exact `--allow-process` grant, 5 s timeout, 1 MiB caps | implemented (project mode; not an OS sandbox) | `resource_streams`, `stdlib_product` |
| `std:random` | `random.字节/整数` -> `resource.request("random.bytes", [count])`; exact `--allow-random` grant | implemented (project mode; byte-list RNG) | `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` |
@@ -131,7 +132,7 @@ that a phase is complete.
| P1 | CLI split into `commands/{sandbox,run,check,inspect,init,package,tool}.rs`; host split into `host/{resource_ops,providers,effects,dispatch}.rs` plus `process.rs`; `commands.rs` keeps shared project/runtime helpers and `host.rs` keeps the `Host` trait methods and capability checks | split; shared helpers and trait methods remain by design |
| 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`, `std:clock`, `std:env` and `std:process` are implemented; no secure random or compression | open |
| P2 | `std:path`, a regex subset, `std:datetime`, `std:clock`, `std:env`, `std:process` and `std:random` are implemented; no 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 |
@@ -166,5 +167,6 @@ that a phase is complete.
- [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants.
- [ADR-0044: `process.run` resource operation](../adr/0044-process-resource-operation.md) — accepted exact-path process grant; not a sandbox.
- [ADR-0045: fs append/read_at/walk](../adr/0045-fs-append-read-at-walk.md) — accepted bounded content and directory walk.
- [ADR-0046: `random.bytes`](../adr/0046-random-resource-operation.md) — accepted explicitly granted OS entropy.
- [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.
+1
View File
@@ -50,6 +50,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and
| `env.get` resource operation | [0043](../adr/0043-env-resource-operation.md) | Accepted (exact-name project grant) |
| `process.run` resource operation | [0044](../adr/0044-process-resource-operation.md) | Accepted (exact program grant, project only, not a sandbox) |
| `fs.append`/`fs.read_at`/`fs.walk` | [0045](../adr/0045-fs-append-read-at-walk.md) | Accepted (bounded content, directory walk) |
| `random.bytes` resource operation | [0046](../adr/0046-random-resource-operation.md) | Accepted (explicit `--allow-random`, project only) |
| 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,38 @@
# Evidence: `std:random` and `random.bytes`
Date: 2026-11-21 (Asia/Shanghai)
Source baseline: `6338fa10e948d9f62f8eea84c793a0c4255e8d66`
Repository: `marqdo-cli`
Decision record: [ADR-0046](../adr/0046-random-resource-operation.md)
## Implemented
`resource.request("random.bytes", [count])` is project-mode only:
- count 1..=65536; other values are fatal type errors;
- exact `--allow-random` grant required; pure/strict refuse;
- bytes come from `getrandom::fill` and are returned as `List<Int>` 0–255;
- one `resource.request` trace/effect event.
`stdlib/random.mq.md` exposes `字节(n)` and `整数(上限)` (8 bytes modulo
upper bound; not claimed unbiased).
## Tests
`stdlib/tests/random.mq.md` runs with `--allow-random` and checks length and
range. `crates/marqdo-host/tests/resource_streams.rs` pins grant denial,
pure-mode refusal, byte range and count validation (25 host tests).
```text
cargo fmt --all -- --check PASS
cargo clippy --workspace --all-targets -- -D warnings PASS
cargo test --workspace 481 passed, 0 failed, 2 ignored
cargo test -p marqdo-host --test resource_streams 25 passed
cargo test -p marqdo-cli --test stdlib_product 15 passed
python3 tools/pack-stdlib.py PASS
```
## Not covered
No unbiased rejection sampling, token/secret API, deterministic seed source or
cryptographic post-processing. The byte list is plain OS entropy.