feat(stdlib): ship a verified bundled stdlib with std: imports

- Move the Compat-A print prototype into stdlib/ as the official offline
  bundle with stdlib.json (version 0.1.0 + sha256 content digest).
- Add std:<relative> import resolution in the loader with bundle path
  confinement, extension inference and fail-closed digest verification.
- Record the verified version/digest/instance_id in Analysis v2
  project.stdlib; stdlib modules get a std:name@version#digest instance id.
- Add CLI tests: std:io execution, digest-tamper rejection, missing manifest,
  Analysis identity, no foreign/plugin calls, and frozen binary hash equality.
- Update ADR-0028, specs, status, changelog and evidence.

Gate: fmt, clippy -D warnings, 415 tests passed.
This commit is contained in:
cflmy committed 2026-11-20 21:43:14 +08:00
1 parent 1a978c7a42
commit 1377af1601
28 files changed
+879 -23

No files matched your search

+5
View File
@@ -61,6 +61,11 @@ pub fn build(project: &LoadedProject) -> Value {
"root_id": project.identity.root_id(),
"identity_kind": project.identity.kind(),
"lock_digest": lock_digest(project),
"stdlib": project.stdlib.as_ref().map(|stdlib| json!({
"version": stdlib.version,
"digest": stdlib.digest,
"instance_id": stdlib.instance_id,
})),
},
"modules": modules,
"diagnostics": diagnostics_json(project),
+34 -1
View File
@@ -20,6 +20,8 @@ use marqdo_package::{
};
use marqdo_value::{codes, Diagnostic};
use crate::stdlib::StdlibBundle;
/// One analysed source file.
pub struct LoadedFile {
/// Canonical module identity (package instance + package-relative path).
@@ -125,6 +127,17 @@ pub struct LocatedSource<'a> {
pub column: usize,
}
/// Identity of the verified bundled stdlib used by a load, if any.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StdlibInfo {
/// Declared version.
pub version: String,
/// Verified content digest.
pub digest: String,
/// Package instance id.
pub instance_id: String,
}
/// A fully loaded project ready for checking or running.
pub struct LoadedProject {
/// Project root.
@@ -141,6 +154,8 @@ pub struct LoadedProject {
pub packages: BTreeMap<String, PathBuf>,
/// All diagnostics in deterministic order.
pub diagnostics: Vec<FileDiagnostic>,
/// Verified bundled stdlib identity, when one was available.
pub stdlib: Option<StdlibInfo>,
}
impl LoadedProject {
@@ -205,6 +220,7 @@ struct Loader {
program: Program,
diagnostics: Vec<FileDiagnostic>,
stack: Vec<PathBuf>,
stdlib: Option<StdlibBundle>,
}
/// Load the entry file and its explicitly imported modules.
@@ -250,6 +266,7 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
};
let resolver = PackageResolver::new(root.clone(), manifest.clone(), lock);
let entry_module = resolver.resolve_entry(&entry)?;
let stdlib = StdlibBundle::discover().map_err(|error| format!("stdlib: {error}"))?;
let mut loader = Loader {
resolver,
packages: BTreeMap::new(),
@@ -257,6 +274,7 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
program: Program::default(),
diagnostics: Vec::new(),
stack: Vec::new(),
stdlib,
};
let entry_id = loader.load_module(&entry_module.package, &entry_module.relative_path)?;
loader.program.main_module = Some(entry_id.clone());
@@ -270,6 +288,11 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
});
}
}
let stdlib_info = loader.stdlib.as_ref().map(|bundle| StdlibInfo {
version: bundle.version().to_string(),
digest: bundle.digest().to_string(),
instance_id: bundle.instance_id(),
});
let identity = match &manifest {
Some(_) => ProjectIdentity::Manifest {
instance: entry_id.instance.clone(),
@@ -286,6 +309,7 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
files: loader.files,
packages: loader.packages,
diagnostics: loader.diagnostics,
stdlib: stdlib_info,
})
}
@@ -360,7 +384,16 @@ impl Loader {
.unwrap_or_default();
for (alias, target, span) in imports {
let resolved = if let Some(alias_name) = target.strip_prefix('@') {
let resolved = if let Some(std_target) = target.strip_prefix("std:") {
match &self.stdlib {
Some(stdlib) => stdlib.resolve(std_target),
None => Err(format!(
"no bundled stdlib is available for `{target}`; install the official \
CLI bundle or set {STDLIB_DIR_ENV}",
STDLIB_DIR_ENV = crate::stdlib::STDLIB_DIR_ENV
)),
}
} else if let Some(alias_name) = target.strip_prefix('@') {
self.resolver.resolve_alias_from(package, alias_name)
} else {
self.resolver.resolve_relative(package, &path, &target)
+1
View File
@@ -9,6 +9,7 @@ mod args;
mod commands;
mod loader;
mod output;
mod stdlib;
mod tool;
mod trace;
+260
View File
@@ -0,0 +1,260 @@
//! Bundled standard library discovery, digest verification and `std:` imports.
//!
//! The official CLI ships a fixed `marqdo-stdlib` tree (ADR-0026/CM-A10). This
//! module finds that tree, verifies its declared content digest before any
//! module is loaded, and resolves explicit `std:<relative>` imports to it.
//! Nothing is fetched implicitly and there is no second module search path.
use std::path::{Component, Path, PathBuf};
use marqdo_package::{PackageOrigin, ResolvedModule, ResolvedPackage};
use sha2::{Digest, Sha256};
/// Environment override used by tests and relocatable installations.
pub const STDLIB_DIR_ENV: &str = "MARQDO_STDLIB_DIR";
/// Verified bundled standard library.
#[derive(Debug, Clone)]
pub struct StdlibBundle {
root: PathBuf,
name: String,
version: String,
digest: String,
}
impl StdlibBundle {
/// Discover the bundle.
///
/// Order: `MARQDO_STDLIB_DIR` (explicit, fail if invalid), a `stdlib`
/// directory next to the executable, then the development tree.
pub fn discover() -> Result<Option<Self>, String> {
if let Some(dir) = std::env::var_os(STDLIB_DIR_ENV) {
return Self::load(PathBuf::from(dir)).map(Some);
}
if let Ok(exe) = std::env::current_exe() {
if let Some(parent) = exe.parent() {
let candidate = parent.join("stdlib");
if candidate.is_dir() {
return Self::load(candidate).map(Some);
}
}
}
let dev = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("..")
.join("..")
.join("stdlib");
if dev.is_dir() {
return Self::load(dev).map(Some);
}
Ok(None)
}
/// Load and verify one bundle directory.
pub fn load(root: impl Into<PathBuf>) -> Result<Self, String> {
let root = root.into();
let root = root.canonicalize().map_err(|error| {
format!("cannot open stdlib directory `{}`: {error}", root.display())
})?;
let manifest_path = root.join("stdlib.json");
let text = std::fs::read_to_string(&manifest_path)
.map_err(|error| format!("cannot read `{}`: {error}", manifest_path.display()))?;
let manifest: serde_json::Value = serde_json::from_str(&text)
.map_err(|error| format!("invalid `{}`: {error}", manifest_path.display()))?;
let name = manifest
.get("name")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| format!("`{}` has no name", manifest_path.display()))?
.to_string();
let version = manifest
.get("version")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| format!("`{}` has no version", manifest_path.display()))?
.to_string();
let declared = manifest
.get("digest")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| format!("`{}` has no digest", manifest_path.display()))?
.to_string();
let actual = tree_digest(&root)?;
if declared != actual {
return Err(format!(
"stdlib digest mismatch: declared {declared}, actual {actual}"
));
}
Ok(Self {
root,
name,
version,
digest: actual,
})
}
/// Declared stdlib version.
pub fn version(&self) -> &str {
&self.version
}
/// Verified content digest (`sha256:<hex>`).
pub fn digest(&self) -> &str {
&self.digest
}
/// Logical package identity used for module ids.
pub fn instance_id(&self) -> String {
format!(
"std:{}@{}#{}",
self.name,
self.version,
self.digest.trim_start_matches("sha256:")
)
}
/// Package view consumed by the loader.
pub fn package(&self) -> ResolvedPackage {
ResolvedPackage {
instance_id: self.instance_id(),
name: self.name.clone(),
version: self.version.clone(),
origin: PackageOrigin::Path {
declared: PathBuf::from("stdlib"),
},
revision: None,
content_digest: Some(self.digest.clone()),
module_root: self.root.clone(),
entry_module: "index.mq.md".to_string(),
manifest: None,
}
}
/// Resolve a `std:<relative>` target inside the bundle.
pub fn resolve(&self, target: &str) -> Result<ResolvedModule, String> {
let mut normalised = PathBuf::new();
for component in Path::new(target).components() {
match component {
Component::Normal(part) => normalised.push(part),
Component::CurDir => {}
Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
return Err(format!(
"stdlib import `{target}` must be a relative path inside the stdlib"
))
}
}
}
if normalised.as_os_str().is_empty() {
return Err("stdlib import must name a module".to_string());
}
if normalised.extension().is_none() {
normalised.set_extension("mq.md");
}
let candidate = self.root.join(&normalised);
let canonical = candidate.canonicalize().map_err(|error| {
format!(
"cannot open stdlib module `{target}` at `{}`: {error}",
candidate.display()
)
})?;
let relative = canonical
.strip_prefix(&self.root)
.map_err(|_| format!("stdlib import `{target}` escapes the stdlib root"))?;
let relative_path = relative
.components()
.map(|component| component.as_os_str().to_string_lossy().to_string())
.collect::<Vec<_>>()
.join("/");
Ok(ResolvedModule {
package: self.package(),
relative_path,
})
}
}
/// Content digest over all `.mq.md` files: sorted path, NUL, bytes, NUL.
pub fn tree_digest(root: &Path) -> Result<String, String> {
let mut files = Vec::new();
collect_markdown(root, root, &mut files)?;
files.sort();
let mut hasher = Sha256::new();
for (relative, path) in files {
let bytes = std::fs::read(&path)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
hasher.update(relative.as_bytes());
hasher.update([0]);
hasher.update(&bytes);
hasher.update([0]);
}
Ok(format!("sha256:{}", hex(&hasher.finalize())))
}
fn collect_markdown(
root: &Path,
dir: &Path,
out: &mut Vec<(String, PathBuf)>,
) -> Result<(), String> {
let entries = std::fs::read_dir(dir)
.map_err(|error| format!("cannot read `{}`: {error}", dir.display()))?;
for entry in entries {
let entry = entry.map_err(|error| format!("cannot read `{}`: {error}", dir.display()))?;
let path = entry.path();
if path.is_dir() {
collect_markdown(root, &path, out)?;
} else if path
.file_name()
.is_some_and(|name| name.to_string_lossy().ends_with(".mq.md"))
{
let relative = path
.strip_prefix(root)
.map_err(|_| "stdlib file escaped its root".to_string())?
.components()
.map(|component| component.as_os_str().to_string_lossy().to_string())
.collect::<Vec<_>>()
.join("/");
out.push((relative, path));
}
}
Ok(())
}
fn hex(bytes: &[u8]) -> String {
let mut out = String::with_capacity(bytes.len() * 2);
for byte in bytes {
out.push_str(&format!("{byte:02x}"));
}
out
}
#[cfg(test)]
mod tests {
use super::*;
fn dev_bundle() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("..")
.join("..")
.join("stdlib")
}
#[test]
fn dev_bundle_verifies_and_resolves() {
let bundle = StdlibBundle::load(dev_bundle()).unwrap();
assert!(bundle.digest.starts_with("sha256:"));
let io = bundle.resolve("io").unwrap();
assert_eq!(io.relative_path, "io.mq.md");
assert!(io.package.instance_id.starts_with("std:marqdo-stdlib@"));
assert!(bundle.resolve("../escape").is_err());
}
#[test]
fn digest_tamper_is_rejected() {
let dir = tempfile::tempdir().unwrap();
let source = dev_bundle();
for entry in std::fs::read_dir(&source).unwrap() {
let entry = entry.unwrap();
if entry.path().is_file() {
std::fs::copy(entry.path(), dir.path().join(entry.file_name())).unwrap();
}
}
std::fs::write(dir.path().join("io.mq.md"), "## tampered\n").unwrap();
let error = StdlibBundle::load(dir.path()).unwrap_err();
assert!(error.contains("digest mismatch"), "{error}");
}
}