feat(random): add explicitly granted OS entropy API
This commit is contained in:
1 parent
6338fa10e9
commit
ee0c6cc80a
20 files changed
+309
-15
No files matched your search
+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
|
||||
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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user