docs(security): gate strict-mode availability behind a security test lane (H3-B)

Add ADR-0019 freezing the strict availability contract: strict remains
unavailable with an actionable reason on every platform until runtime probes
and filesystem/network/process/resource escape tests pass in a dedicated
security lane. Add a CLI test asserting inspect --platform reports unavailable
and worker processes are not presented as isolation. No G-C claim is made.
This commit is contained in:
cflmy committed 2026-11-20 13:13:42 +08:00
1 parent 1099ed6160
commit e966b7661f
3 files changed
+113 -1

No files matched your search

+25
View File
@@ -739,3 +739,28 @@ fn runtime_error_in_imported_module_reports_that_module() {
.unwrap_or_default();
assert!(primary.contains("physics.mq.md"), "{primary}");
}
#[test]
fn platform_reports_strict_unavailable_until_security_gate_passes() {
let root = repo_root();
let hello = root.join("examples").join("hello.mq.md");
let output = cli(
&root,
&["inspect", hello.to_str().unwrap(), "--platform", "--json"],
);
assert_exit(&output, 0, "inspect --platform");
let value = json_stdout(&output);
let strict = &value["platform"]["strict"];
assert_eq!(
strict["state"], "unavailable",
"strict must stay unavailable until the ADR-0019 security gate passes: {strict}"
);
assert!(
strict["reason"]
.as_str()
.map(|reason| !reason.trim().is_empty())
.unwrap_or(false),
"unavailable strict needs an actionable reason: {strict}"
);
assert_eq!(value["platform"]["worker_processes"], true);
}
+2 -1
View File
@@ -232,7 +232,8 @@ Foreign provider integrity and environment metadata:
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
| S5-A/B-12 foreign integrity | **Done for pinned provider+environment** | provider and environment-directory digests verified at registration and before spawn; environment bin/PATH injection. uv/npm environment generation, lock-v3 integration and H3-B remain open (see §S5-A/B-12) |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth and H3-B OS isolation remain open and are not claimed (ADR-0018) |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth remains open (ADR-0018) |
| S5-C/H3-B strict gate | **Gate implemented; isolation deferred** | ADR-0019 + test: strict stays unavailable with an actionable reason until a per-platform security lane passes; refusal is enforced before host/plugin creation. No G-C claim |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
@@ -0,0 +1,86 @@
# ADR-0019: Strict-mode availability gate
Status: **Accepted**
Date: 2026-11-20
Relates to: ADR-0004 (strict mode refuses without isolation), blueprint §9
## Context
`strict` is the only mode that may claim isolation for untrusted documents.
The project must never advertise strict execution merely because an isolated
worker process or a cooperative path check exists. At the time of this ADR no
platform adapter has passed the required OS-level escape and resource tests.
The environment used for this stabilization work cannot create namespaces
(`unshare`/`bwrap` return "Operation not permitted"), so a real Linux adapter
cannot be built *and verified* here. Landlock is present but covers filesystem
rules only; it does not by itself satisfy the network/process/resource and
child-tree requirements in `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`
§13.
## Decision
### 1. Strict stays unavailable until the gate passes
`PlatformCapabilities::detect` reports `StrictIsolation::Unavailable` with a
platform-specific reason on every platform. `enforce` refuses strict before any
host or plugin is constructed. There is no fallback to `project`, no "warn and
continue", and no opt-in flag that silently disables the refusal.
This state is deliberate design output, not an incomplete branch: G-B does not
depend on it, and every unsupported platform must fail closed.
### 2. Availability is a per-platform, test-gated decision
A platform may report `Available { mechanism }` only when all of the following
hold on that platform and are covered by CI on a dedicated security lane:
* filesystem visibility restricted to the project and explicit grants;
escapes via `..`, absolute paths, symlinks and TOCTOU are denied;
* network socket creation/connection denied unless explicitly granted;
* process creation denied unless explicitly granted; the child tree is reaped
and leaves no orphans;
* resource limits for CPU, memory, file descriptors, process count, output and
wall clock are enforced;
* plugin workers and foreign kernels inherit the same restrictions, or strict
refuses to load them;
* the adapter is probed at runtime; failure to obtain the mechanisms leaves
strict `Unavailable` with the real reason;
* `--trust-native-plugin` and in-process native loading are rejected in strict,
since C ABI code shares the host address space;
* a probe/escape test suite demonstrates denial of reading `/etc/...`, writing
outside the project, connecting to the network and spawning a process.
Until then, `strict` must refuse even when other flags (`--allow-foreign`,
`--plugin`, `--trust-native-plugin`, read/write grants) are present.
### 3. Capability execution is not isolation
The broker executing `fs.read` for native and worker plugins (ADR-0018) is a
cooperative API contract with audit; it does not prevent a plugin from issuing
direct syscalls. It is not evidence for strict availability.
### 4. Observability
`marqdo inspect --platform --json` exposes the state and reason. The CLI test
suite asserts that the state is `unavailable` and that a strict run exits 1 with
a refusal message. Changing this contract requires this ADR to be superseded
together with the security test suite.
## Consequences
* No G-C claim is made. Documentation and CI must not describe worker
processes, Landlock-only filesystems or in-process brokers as a sandbox.
* A future adapter must add a new ADR, runtime probe, security lane and negative
tests before flipping `Unavailable` to `Available`.
* Platform-specific reasons remain actionable but do not leak secrets or host
layout details.
## Tests
* `strict_mode_refuses_without_isolation` (CLI): refusal, exit 1, no stdout,
JSON error envelope.
* `platform_reports_strict_unavailable` (CLI): `inspect --platform --json`
reports `state: unavailable` with a non-empty reason.
* Existing worker tests remain explicitly labelled crash isolation, not OS
isolation.