From 00bdcad1ff208e65100964b339a6640c85e54115 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 23:05:06 +0800 Subject: [PATCH] feat(host): add IP-literal blocking TCP resource endpoint (P5) - resource.open("tcp", ip:port, ["read","write"]) with exact IP grants, project mode only, 5s connect/read/write timeouts; no DNS/TLS/UDP/server sockets (ADR-0034). - Add TCP stream storage/dispatch in the resource table; CLI --allow-net IP; pure/strict preflight rejects the grant and the language endpoint. - Host loopback echo/grant/DNS/strict tests and a .mq.md CLI echo test. - Update specs, status, architecture, README, changelog and evidence. Gate: fmt, clippy -D warnings, 426 tests passed. --- CHANGELOG.md | 4 + README.md | 3 + crates/cli/src/commands.rs | 7 ++ crates/cli/src/main.rs | 4 + crates/cli/tests/resource_streams.rs | 62 +++++++++++++++ crates/marqdo-host/src/capability.rs | 6 ++ crates/marqdo-host/src/host.rs | 49 ++++++++++++ crates/marqdo-host/src/resource.rs | 42 ++++++++++ crates/marqdo-host/tests/resource_streams.rs | 79 ++++++++++++++++++ docs/STATUS.md | 8 +- docs/adr/0034-tcp-resource-endpoint.md | 84 ++++++++++++++++++++ docs/architecture/README.md | 1 + docs/evidence/2026-11-20-tcp-endpoint.md | 78 ++++++++++++++++++ spec/security.md | 6 +- tests/README.md | 6 ++ 15 files changed, 435 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0034-tcp-resource-endpoint.md create mode 100644 docs/evidence/2026-11-20-tcp-endpoint.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 18553e9..7ce2da8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -125,6 +125,10 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601. before module loading, a `std:marqdo-stdlib@#` package instance id, `project.stdlib` in Analysis v2, and test coverage for `std:` resolution, tamper rejection and frozen-binary hash equality. +- P5 blocking TCP endpoint v1 (ADR-0034): `resource.open("tcp", ip:port, + ["read","write"])` with exact IP-literal grants, project mode only, 5s + connect/read/write timeouts; no DNS/TLS/UDP/server sockets. CLI `--allow-net + `; loopback host and `.mq.md` echo tests. Strict/pure refuse. - CM-A09 in-process ResourceProvider v1 (ADR-0033): `ResourceProvider` trait, `StdHost::register_resource_provider`, per-kind registration with protocol version/conflict checks and `Capabilities.allow_resource_provider`; provider diff --git a/README.md b/README.md index 7844502..beb2c3a 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,9 @@ executes anything. `.mq.md` print chain is the only execution path for `打印`/`print` on an official install (ADR-0031), covering all 15 value types; `HostOp::Print` and the legacy formatter are removed (ADR-0027/0028/0029/0030/0031). +* **Blocking TCP endpoint (RFC-CM P5 first slice)** — `resource.open("tcp", + ":", ["read","write"])` with exact IP grants, project mode and + 5-second timeouts; DNS/TLS/UDP/server sockets excluded (ADR-0034). * **In-process ResourceProvider v1 (RFC-CM CM-A09 first slice)** — trusted providers register extra resource kinds, project-mode + name-grant gated, using the existing `resource.*`/`Result` ABI; no parser/runtime/`HostOp` diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index 9c969a7..4bb891a 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -22,6 +22,8 @@ pub struct SandboxSettings { pub allow_read: Vec, /// Write grants. pub allow_write: Vec, + /// Network grants (IP literals, ADR-0034). + pub allow_net: Vec, /// Foreign execution grant. pub allow_foreign: bool, /// Plugin grants. @@ -70,6 +72,7 @@ impl SandboxSettings { pub fn strict_preflight(&self) -> Result<(), String> { let requested = self.allow_foreign || !self.allow_read.is_empty() + || !self.allow_net.is_empty() || !self.allow_write.is_empty() || !self.allow_plugin.is_empty() || !self.plugins.is_empty() @@ -94,6 +97,7 @@ impl SandboxSettings { match mode { SandboxMode::Pure => { if !self.allow_read.is_empty() + || !self.allow_net.is_empty() || !self.allow_write.is_empty() || self.allow_foreign || !self.allow_plugin.is_empty() @@ -112,6 +116,9 @@ impl SandboxSettings { for pattern in &self.allow_write { capabilities = capabilities.allow_write(pattern.clone()); } + for host in &self.allow_net { + capabilities = capabilities.allow_net(host.clone()); + } if self.allow_foreign { capabilities = capabilities.allow_foreign(); } diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 40c9878..b7f2fe7 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -86,6 +86,9 @@ struct SandboxArgs { /// Grant read access to a project-relative glob (repeatable). #[arg(long = "allow-read", value_name = "GLOB")] allow_read: Vec, + /// Grant network access to an IP literal host (repeatable, ADR-0034). + #[arg(long = "allow-net", value_name = "IP")] + allow_net: Vec, /// Grant write access to a project-relative glob (repeatable). #[arg(long = "allow-write", value_name = "GLOB")] allow_write: Vec, @@ -138,6 +141,7 @@ impl SandboxArgs { commands::SandboxSettings { mode: self.mode.clone(), allow_read: self.allow_read.clone(), + allow_net: self.allow_net.clone(), allow_write: self.allow_write.clone(), allow_foreign: self.allow_foreign, allow_plugin: self.allow_plugin.clone(), diff --git a/crates/cli/tests/resource_streams.rs b/crates/cli/tests/resource_streams.rs index 944270b..e09d092 100644 --- a/crates/cli/tests/resource_streams.rs +++ b/crates/cli/tests/resource_streams.rs @@ -222,6 +222,68 @@ fn file_copy_is_written_in_mqmd_through_chunked_streams() { ); } +#[test] +fn tcp_stream_round_trips_through_mqmd_with_a_network_grant() { + use std::io::{Read, Write}; + use std::net::TcpListener; + + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap(); + let server = std::thread::spawn(move || { + let (mut stream, _) = listener.accept().unwrap(); + let mut buffer = [0u8; 4]; + stream.read_exact(&mut buffer).unwrap(); + stream.write_all(&buffer).unwrap(); + }); + + let dir = TempDir::new("tcp"); + let program = format!( + r#"## main + +**内存 = memory.new(1, 1)** + +**`内存[0] = 112`** + +**`内存[1] = 105`** + +**`内存[2] = 110`** + +**`内存[3] = 103`** + +**流 = resource.open("tcp", "{address}", ["read", "write"])** + +**写入 = resource.write(流, 内存, 0, 4)** + +**读出 = resource.read(流, 内存, 0, 4)** + +**关闭 = resource.close(流)** + +*[写入.value.count, 读出.value.count, 内存[0], 内存[1], 内存[2], 内存[3], 关闭.ok]* +"# + ); + write_file(&dir.path().join("index.mq.md"), &program); + let output = cli( + dir.path(), + &["run", "index.mq.md", "--allow-net", "127.0.0.1", "--json"], + ); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report: serde_json::Value = serde_json::from_slice(&output.stdout).expect("json output"); + assert_eq!(report["success"], true); + let values = report["value"]["items"].as_array().expect("list"); + assert_eq!(values[0]["decimal"], "4"); + assert_eq!(values[1]["decimal"], "4"); + for (index, expected) in ["112", "105", "110", "103"].into_iter().enumerate() { + assert_eq!(values[2 + index]["decimal"], expected); + } + assert_eq!(values[6]["value"], true); + server.join().unwrap(); +} + #[test] fn file_stream_requires_a_read_grant() { let dir = TempDir::new("file-denied"); diff --git a/crates/marqdo-host/src/capability.rs b/crates/marqdo-host/src/capability.rs index 0c53b0f..2b51837 100644 --- a/crates/marqdo-host/src/capability.rs +++ b/crates/marqdo-host/src/capability.rs @@ -374,6 +374,12 @@ impl Capabilities { self } + /// Grant network access to one IP literal host (ADR-0034). + pub fn allow_net(mut self, host: impl Into) -> Self { + self.net_hosts.push(host.into()); + self + } + /// Grant a registered resource provider by its stable name (ADR-0033). pub fn allow_resource_provider(mut self, name: impl Into) -> Self { self.resource_providers.push(name.into()); diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 95ce70a..0a2a878 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -5,6 +5,7 @@ //! execution, not at parse/compile time. use std::collections::{BTreeMap, BTreeSet}; +use std::net::{SocketAddr, TcpStream}; use std::sync::{Arc, Mutex}; use std::time::{Duration, Instant}; @@ -755,6 +756,54 @@ impl StdHost { "project file streams support exactly [read] or [write] in this build", )) } + "tcp" => { + if self.mode != SandboxMode::Project { + return Err(RuntimeError::new( + ErrorCategory::PermissionDenied, + ctx.span, + "tcp resources are available only in project mode", + )); + } + if requested != BTreeSet::from(["read", "write"]) { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + "tcp resources require exactly [read, write] in this build", + )); + } + let address: SocketAddr = descriptor.parse().map_err(|_| { + RuntimeError::new( + ErrorCategory::ResourceUnsupported, + ctx.span, + format!( + "tcp descriptor `{descriptor}` must be an IP literal address:port (DNS names are not resolved in this build)" + ), + ) + })?; + self.capabilities + .check_net(&address.ip().to_string(), ctx.span)?; + let stream = TcpStream::connect_timeout(&address, Duration::from_secs(5)).map_err( + |error| { + RuntimeError::new( + ErrorCategory::HostError, + ctx.span, + format!("cannot connect to {address}: {error}"), + ) + }, + )?; + let _ = stream.set_read_timeout(Some(Duration::from_secs(5))); + let _ = stream.set_write_timeout(Some(Duration::from_secs(5))); + let handle = self.resources.open_tcp(stream); + self.record_semantic( + "resource.open", + None, + Some(&ctx.module_id), + ctx.span, + Some(&format!("kind=tcp address={address}")), + ); + self.record_resource_effect("resource.open", ctx, started, "ok"); + Ok(Value::Resource(handle)) + } other => { if self.mode != SandboxMode::Project { return Err(RuntimeError::new( diff --git a/crates/marqdo-host/src/resource.rs b/crates/marqdo-host/src/resource.rs index 8bb542a..578088b 100644 --- a/crates/marqdo-host/src/resource.rs +++ b/crates/marqdo-host/src/resource.rs @@ -5,6 +5,8 @@ //! table validates run identity, slot identity and generation on every call. use std::collections::BTreeMap; +use std::io::{Read, Write}; +use std::net::TcpStream; use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::{Arc, Mutex}; @@ -85,6 +87,10 @@ enum Stream { token: u64, closed: bool, }, + Tcp { + stream: TcpStream, + closed: bool, + }, } struct Slot { @@ -99,6 +105,7 @@ impl Slot { Stream::File { closed, .. } => *closed, Stream::FileWriter { closed, .. } => *closed, Stream::Provider { closed, .. } => *closed, + Stream::Tcp { closed, .. } => *closed, } } } @@ -155,6 +162,14 @@ impl ResourceTable { }) } + /// Register a connected TCP stream. + pub fn open_tcp(&mut self, stream: TcpStream) -> ResourceHandle { + self.insert(Stream::Tcp { + stream, + closed: false, + }) + } + /// Open a provider token and wrap it in a host-issued handle. pub fn open_provider( &mut self, @@ -272,6 +287,21 @@ impl ResourceTable { let mut provider = provider.lock().map_err(|_| provider_lock_error(span))?; provider.read(*token, max_bytes, span) } + Stream::Tcp { stream, .. } => { + let mut buffer = vec![0u8; max_bytes]; + let count = stream.read(&mut buffer).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("tcp read failed: {error}"), + ) + })?; + buffer.truncate(count); + Ok(ResourceRead { + bytes: buffer, + eof: count == 0, + }) + } } } @@ -332,6 +362,13 @@ impl ResourceTable { let mut provider = provider.lock().map_err(|_| provider_lock_error(span))?; provider.write(*token, bytes, span) } + Stream::Tcp { stream, .. } => stream.write(bytes).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("tcp write failed: {error}"), + ) + }), } } @@ -363,6 +400,10 @@ impl ResourceTable { provider.close(*token, span)?; *closed = true; } + Stream::Tcp { stream, closed } => { + let _ = stream.shutdown(std::net::Shutdown::Both); + *closed = true; + } } Ok(()) } @@ -400,6 +441,7 @@ impl ResourceTable { Stream::Stdout { .. } => "stdio".to_string(), Stream::File { .. } | Stream::FileWriter { .. } => "file".to_string(), Stream::Provider { kind, .. } => kind.clone(), + Stream::Tcp { .. } => "tcp".to_string(), }) } } diff --git a/crates/marqdo-host/tests/resource_streams.rs b/crates/marqdo-host/tests/resource_streams.rs index 59795ec..7487ef2 100644 --- a/crates/marqdo-host/tests/resource_streams.rs +++ b/crates/marqdo-host/tests/resource_streams.rs @@ -375,3 +375,82 @@ fn provider_registration_rejects_versions_reserved_names_and_conflicts() { .unwrap_err(); assert_eq!(conflict.category, ErrorCategory::ResourceUnsupported); } + +#[test] +fn tcp_resource_round_trips_with_a_network_grant() { + use std::io::{Read, Write}; + use std::net::TcpListener; + + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap(); + let server = std::thread::spawn(move || { + let (mut stream, _) = listener.accept().unwrap(); + let mut buffer = [0u8; 4]; + stream.read_exact(&mut buffer).unwrap(); + stream.write_all(&buffer).unwrap(); + }); + + let dir = tempfile::tempdir().unwrap(); + let mut host = StdHost::new( + SandboxMode::Project, + Capabilities::project().allow_net("127.0.0.1"), + dir.path(), + ); + let ctx = context(); + let handle = handle( + host.resource_open( + "tcp", + &address.to_string(), + &["read".to_string(), "write".to_string()], + &ctx, + ) + .unwrap(), + ); + assert_eq!(host.resource_write(handle, b"ping", &ctx).unwrap(), 4); + let read = host.resource_read(handle, 4, &ctx).unwrap(); + assert_eq!(read.bytes, b"ping"); + host.resource_close(handle, &ctx).unwrap(); + server.join().unwrap(); +} + +#[test] +fn tcp_requires_network_grant_and_rejects_dns_names() { + let dir = tempfile::tempdir().unwrap(); + let mut host = StdHost::new(SandboxMode::Project, Capabilities::project(), dir.path()); + let ctx = context(); + let denied = host + .resource_open( + "tcp", + "127.0.0.1:9", + &["read".to_string(), "write".to_string()], + &ctx, + ) + .unwrap_err(); + assert_eq!(denied.category, ErrorCategory::PermissionDenied); + let dns = host + .resource_open( + "tcp", + "example.test:80", + &["read".to_string(), "write".to_string()], + &ctx, + ) + .unwrap_err(); + assert_eq!(dns.category, ErrorCategory::ResourceUnsupported); + + for mode in [SandboxMode::Pure, SandboxMode::Strict] { + let mut host = StdHost::new( + mode, + Capabilities::project().allow_net("127.0.0.1"), + dir.path(), + ); + let error = host + .resource_open( + "tcp", + "127.0.0.1:9", + &["read".to_string(), "write".to_string()], + &ctx, + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::PermissionDenied); + } +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 2b094b7..09503ed 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -135,6 +135,9 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL PluginHandle `plugin/export` are read-only observation members (host id private); `stdlib/format.mq.md` reproduces builtin `打印`/`repr` for all 15 value types, including Formula/Code/FunctionRef and Code UTF-8 byte length. +- Blocking TCP endpoint (P5 first slice, ADR-0034): project-mode + `resource.open("tcp", ip:port, ["read","write"])` with exact IP grant and + timeouts; no DNS/TLS/UDP/server sockets; strict/pure refuse. CLI `--allow-net`. - In-process ResourceProvider v1 (CM-A09 first slice, ADR-0033): trusted providers register additional resource kinds without parser/runtime/HostOp changes; project-mode + name grant required; pure/strict refuse provider @@ -195,7 +198,7 @@ behavior. This table records only what is in this tree now. | P2 Marqdo-written allocator/data structures + minimal structure observation | **PARTIAL, gate NOT passed** | `.mq.md`-only evidence: bump allocator with u32 codec, linked list, failed-allocation atomicity (48–50); CM-A04 structure primitives and a table filter (51–54, ADR-0023); a first-fit free-list allocator with block reuse, splitting, address-adjacent coalescing and `Result` maps (55, ADR-0024), a `Memory`-backed binary tree with recursive insert/in-order traversal (56), a `.mq.md` CSV row splitter (57), an open-addressing hash table with linear probing, update and `hash.full` (58), a `.mq.md` UTF-8 encoder over `Memory` (59), a validating UTF-8 decoder rejecting truncated, bad-continuation and surrogate/overlong input (60), a `Memory`-backed graph adjacency list (61), a recursive JSON parser for nested arrays/objects, strings with escapes, integers, booleans, null and error Results (62), a `Memory`-backed stack bytecode VM with PUSH/ADD/MUL/JMP/JZ/HALT (63), big-endian 16/32/64-bit plus LEB128 integer codecs (64), a `.mq.md` table sort rebuilding a new table from `table.row/columns/cell` (65), a table join (67), a quoted/escaped CSV row parser (68), table group (69), and an Int matrix multiply (70); the first-fit allocator also detects double free (`alloc.double_free`). Evidence: [`memory-p2-closure`](evidence/2026-11-20-memory-p2-closure.md), [`structure-api-p2`](evidence/2026-11-20-structure-api-p2.md), [`result-and-free-list-p2`](evidence/2026-11-20-result-and-free-list-p2.md). P2 remaining: publication as a separate external stdlib repository. The bundled `stdlib/` tree, `std:` imports, digest verification, Analysis identity and frozen-CLI closure test are implemented (ADR-0028). C01–C06/C11/C12 each have `.mq.md` evidence, including JSON floats and a JSON formatter. | | P3 Resource/Stream ABI | **PARTIAL** | ADR-0025/0026 CM-A06 slices: opaque `Resource`, `resource.open/read/write/close`, stdout write in pure/project, granted project-file read and buffered project-file write in project, EOF/closed/handle errors, wire/host rejection; strict permits only stdio/stdout and refuses file/network resources. Fixture 66 + CLI/host tests. CM-A07 **Compat-C** is implemented: when a program calls `打印/print`, the loader injects the bundled `stdlib/io.mq.md` and the runtime routes to `io.写值` (all 15 value types, UTF-8 via `Memory`, `resource.write(stdout)`); `HostOp::Print` and the legacy `Value::display()` print path are removed, and a missing bundle fails with `kernel.unavailable`. Strict permits only the existing stdio console channel. Still missing: directories, network, generic provider registry, Table storage, strict file/network resources. | | P4 Table logical/physical migration | **PARTIAL** | ADR-0032/CM-A08: `Value::Table` logical semantics unchanged (T0 `Vec>`); `stdlib/data/table.mq.md` provides select/filter/sort/append/set/join/group as value-returning `.mq.md` functions with input immutability. No T1/T2/T3 physical storage, column store or Memory-backed table. | -| P5 third-party Provider / TCP / HTTP | **PARTIAL** | ADR-0033 in-process `ResourceProvider` v1: explicitly trusted providers register by kind, project-mode only, gated by `Capabilities.allow_resource_provider`, using the existing `resource.*`/`Result` ABI; a mock read/write provider is tested. No C/Worker provider transport, network/socket/TCP/HTTP, clock/random/process/device providers, or provider package installation. | +| P5 third-party Provider / TCP / HTTP | **PARTIAL** | ADR-0034 blocking TCP resource endpoint (`resource.open("tcp", ":", ["read","write"])`, exact IP grant, project-only, 5s timeouts; loopback host+CLI tests). ADR-0033 in-process `ResourceProvider` v1: explicitly trusted providers register by kind, project-mode only, gated by `Capabilities.allow_resource_provider`, using the existing `resource.*`/`Result` ABI; a mock read/write provider is tested. No C/Worker provider transport, DNS/TLS/HTTP framing, UDP, clock/random/process/device providers, or provider package installation. | | P6 performance / native backends | **NOT IMPLEMENTED** | no bytecode/JIT/GPU/QPU work | The P1 memory domain is pure computation: it needs no grant and is available in @@ -236,6 +239,9 @@ user-written allocator is explicitly **not** claimed. - [`evidence/2026-11-20-provider-abi-cm-a09.md`](evidence/2026-11-20-provider-abi-cm-a09.md) — ADR-0033 in-process ResourceProvider v1, grants/mode checks, mock provider read/write and registration rejection cases. +- [`evidence/2026-11-20-tcp-endpoint.md`](evidence/2026-11-20-tcp-endpoint.md) + — ADR-0034 blocking TCP endpoint, IP grants, DNS refusal, loopback host/CLI + echo tests. - [`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md) — G0..G12 matrix and RC decision. - [`security-gate.md`](security-gate.md) — mechanism, attack matrix and strict diff --git a/docs/adr/0034-tcp-resource-endpoint.md b/docs/adr/0034-tcp-resource-endpoint.md new file mode 100644 index 0000000..931626c --- /dev/null +++ b/docs/adr/0034-tcp-resource-endpoint.md @@ -0,0 +1,84 @@ +# ADR-0034: Blocking TCP resource endpoint v1 (CM-A09/P5 first slice) + +Status: **Accepted** +Date: 2026-11-20 +Relates to: `docs/MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md` +(CM-A09, CM-A11, P5), ADR-0025, ADR-0033 +Specs: `spec/evaluation.md`, `spec/security.md` +Evidence: `docs/evidence/2026-11-20-tcp-endpoint.md` + +## Context + +CM-A09/P5 require a real external endpoint reached through the stable resource +ABI, not a new `HostOp` or Rust builtin per application. The in-process +provider slice (ADR-0033) covers trusted adapters; it does not exercise a real +OS byte stream. This ADR adds the first OS endpoint: a blocking TCP stream. + +The scope is deliberately narrow: HTTP/1.1, TLS, DNS, UDP, sockets as a broad +API and nonblocking/async I/O remain standard-library or later work. + +## Decision + +### 1. Resource kind and descriptor + +```text +resource.open("tcp", ":", ["read", "write"]) -> Resource +``` + +* descriptor must parse as a `SocketAddr` containing an **IP literal**. DNS + names are rejected with `resource.unsupported`; no resolver is called. +* rights must be exactly `["read","write"]` in this build. A read-only or + write-only TCP handle is future work. +* `resource.read`/`write`/`close` behave like other streams: + * read returns `{count, eof}`; `count=0` is transport EOF; + * write returns a possibly short count; + * close calls `shutdown(Both)` and marks the handle closed; + * closed/forged/stale handles use the existing `resource.closed` / + `runtime.resource` rules. +* connect, read and write have 5-second timeouts. This is blocking I/O on the + interpreter thread; no async runtime is introduced. + +### 2. Authorization + +* `project` mode only. `pure` and `strict` refuse TCP (`permission.denied`); + strict remains fail-closed (CM-A11), and the G-C lane verifies the refusal. +* `Capabilities.check_net(ip)` requires an exact IP-literal grant. The CLI adds + `--allow-net ` (repeatable); `--allow-net` is refused alongside other + external grants in pure/strict preflight. +* Granting a hostname or a network range does not authorize a different IP; + there is no DNS-based allowlist bypass because DNS is not used. +* No TLS, no proxy, no HTTP parsing in the host. `.mq.md` code composes + protocols over the byte stream. + +### 3. Trace + +`resource.open/read/write/close` effect events are recorded. The trace records +the IP:port for open but never payload bytes or credentials. A TCP endpoint is +an external effect and is not replayed as pure computation. + +### 4. Explicit non-goals + +* DNS, TLS, HTTP/1.1 or HTTP/2 host implementations, proxies, redirects. +* UDP, ICMP, raw sockets, socket options, nonblocking/async/select. +* File descriptors exposed to the language, `setsockopt`, `bind`/`listen` server + sockets. +* Strict-mode TCP and any claim that in-process `std::net` is OS isolation. +* Network provider package installation or a generic socket registry. + +## Consequences + +* `.mq.md` can implement a line protocol/HTTP client parser on top of the TCP + byte stream using the existing Memory/Text/Result primitives. +* The runtime still has no `net.request` builtin or new `HostOp`; a CLI test + opens a local echo server, writes/reads `ping` through `resource.*`, and + closes. +* Blocking timeouts bound a hung peer but do not preempt a blocking syscall + deeper than the OS timeout; this is documented. +* Network tests use loopback only; external network access is not required for + the gate. + +## Verification + +`docs/evidence/2026-11-20-tcp-endpoint.md` records host tests (loopback echo, +grant/pure/strict/DNS refusal) and a CLI `.mq.md` echo test with +`--allow-net 127.0.0.1`, plus the full workspace gate. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 679bd77..c4da8b8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -30,6 +30,7 @@ implementation status lives in `docs/STATUS.md`; frozen behavior is in | CM-A07 Compat-C remove legacy print formatting | [0031](../adr/0031-print-compat-c-remove-host-formatting.md) | Accepted | | CM-A08 table logical value / stdlib algorithms / T0 storage | [0032](../adr/0032-table-logical-value-and-stdlib-algorithms.md) | Accepted | | CM-A09 in-process ResourceProvider v1 | [0033](../adr/0033-in-process-resource-provider-v1.md) | Accepted (trusted in-process slice) | +| P5 blocking TCP resource endpoint v1 | [0034](../adr/0034-tcp-resource-endpoint.md) | Accepted (IP-literal, no DNS/TLS) | | Table physical storage (T1/T2/T3), C/Worker provider transport, strict file/network resources | — | Not decided; do not implement by implication | ## What a future phase must not do diff --git a/docs/evidence/2026-11-20-tcp-endpoint.md b/docs/evidence/2026-11-20-tcp-endpoint.md new file mode 100644 index 0000000..c016a7b --- /dev/null +++ b/docs/evidence/2026-11-20-tcp-endpoint.md @@ -0,0 +1,78 @@ +# RFC-CM P5 evidence: blocking TCP resource endpoint v1 + +Date: 2026-11-20 (Asia/Shanghai) +Repository: `marqdo-cli` +Baseline: `1d87f98` plus this step's changes. +Decision record: [ADR-0034](../adr/0034-tcp-resource-endpoint.md) +Related: [provider v1](2026-11-20-provider-abi-cm-a09.md), [STATUS §5](../STATUS.md). +Scope: IP-literal blocking TCP only; no DNS/TLS/UDP/server sockets. + +## Environment and gate + +Ubuntu 26.04 development container, Linux x86_64, Rust 1.100.0. + +```text +cargo fmt --all -- --check PASS +cargo clippy --workspace --all-targets -- -D warnings PASS +cargo test --workspace --locked PASS + 426 passed, 0 failed, 2 ignored (existing plugin-sdk doc-tests) +``` + +No GitHub CI is available from this checkout; this is local evidence. + +## Contract + +```text +resource.open("tcp", ":", ["read", "write"]) +``` + +* project mode only; `pure`/`strict` refuse; +* exact IP-literal grant (`Capabilities.check_net`), CLI `--allow-net `; +* DNS names rejected with `resource.unsupported` (no resolver is called); +* connect/read/write timeouts 5 seconds; blocking I/O on the interpreter thread; +* `resource.read` returns `{count, eof}`, `write` a possibly short count, + `close` shuts the socket down; closed/forged handles use existing rules; +* trace records `resource.open/read/write/close` effects (IP:port on open, no + payload bytes). + +No new `HostOp`, `Value`, builtin or Markdown syntax. + +## Tests + +Host (`crates/marqdo-host/tests/resource_streams.rs`, 2 TCP tests): + +```text +tcp_resource_round_trips_with_a_network_grant + loopback echo: write ping -> read ping -> close + +tcp_requires_network_grant_and_rejects_dns_names + no --allow-net -> permission.denied + "example.test:80" -> resource.unsupported + pure/strict -> permission.denied +``` + +CLI (`crates/cli/tests/resource_streams.rs`): + +```text +tcp_stream_round_trips_through_mqmd_with_a_network_grant + local TcpListener; .mq.md writes/reads 4 bytes through Memory; + run --allow-net 127.0.0.1 --json -> [4,4,112,105,110,103,true] +``` + +## Not done + +* DNS, TLS, HTTP framing, proxies, UDP, raw sockets, socket options. +* Nonblocking/async/select and server bind/listen. +* Strict-mode TCP and any claim that `std::net` in-process is OS isolation. +* Provider package installation/registry for network endpoints. + +## Reproduce + +```bash +export PATH=/root/.cargo/bin:$PATH +export CARGO_HOME=/root/work/marqdo-cli/.cache/cargo +export CARGO_TARGET_DIR=/root/work/marqdo-cli/.cache/target +cargo test -p marqdo-host --test resource_streams tcp +cargo test -p marqdo-cli --test resource_streams tcp +cargo test --workspace --locked +``` diff --git a/spec/security.md b/spec/security.md index 0b267dd..e8338ab 100644 --- a/spec/security.md +++ b/spec/security.md @@ -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 stdout write, granted project-file read/write (ADR-0025/0026) and granted in-process provider kinds (ADR-0033); network/process 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); file/network/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030). `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-foreign`, `--allow-plugin` add grants. `resource.open` supports stdout write, granted project-file read/write (ADR-0025/0026), 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); file/TCP/provider/process resources remain refused until a provider passes the isolation lane (CM-A11, ADR-0030/0034). `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. | `marqdo inspect --platform` prints the detection report, for example: @@ -59,7 +59,7 @@ set for one run: | `math: bool` | `true` | `math.*` host ops | | `fs_read: Vec` | empty | `fs.read` and project `resource.open("file", path, ["read"])` | | `fs_write: Vec` | empty | `fs.write` and project `resource.open("file", path, ["write"])` | -| `net_hosts: Vec` | empty | `Capabilities::check_net` exists, but no host op or builtin performs network access in this build | +| `net_hosts: Vec` | empty | exact IP-literal grants for `resource.open("tcp", ":", ["read","write"])`; DNS is not resolved; `--allow-net ` adds a grant (ADR-0034) | | `process: bool` | `false` | required together with `foreign` for `foreign.run`/`foreign.call` | | `foreign: bool` | `false` | foreign kernels | | `plugins: Vec` | empty | `plugin.invoke` and `StdHost::load_plugin` | diff --git a/tests/README.md b/tests/README.md index 5de08d1..c931d38 100644 --- a/tests/README.md +++ b/tests/README.md @@ -171,6 +171,12 @@ by: * fixture 55 additionally has a second-free detection path: freeing an already-free block returns `{ok:false, code:"alloc.double_free"}`. +P5 TCP endpoint v1 (ADR-0034) is pinned by two host tests in +`crates/marqdo-host/tests/resource_streams.rs` (loopback echo with a grant; +grant/pure/strict/DNS refusal) and +`crates/cli/tests/resource_streams.rs::tcp_stream_round_trips_through_mqmd_with_a_network_grant` +(`--allow-net 127.0.0.1`). + RFC-CM CM-A09 in-process provider v1 (ADR-0033) is pinned by the three `registered_provider_streams_*` / `provider_*` tests in `crates/marqdo-host/tests/resource_streams.rs`: a mock provider is registered