mustardscript 0.1.0

package/crates/mustard/src/span.rs

@@ -0,0 +1,22 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SourceSpan {
+    pub start: u32,
+    pub end: u32,
+}
+
+impl SourceSpan {
+    pub const fn new(start: u32, end: u32) -> Self {
+        Self { start, end }
+    }
+}
+
+impl From<oxc_span::Span> for SourceSpan {
+    fn from(value: oxc_span::Span) -> Self {
+        Self {
+            start: value.start,
+            end: value.end,
+        }
+    }
+}

package/crates/mustard/src/structured.rs

@@ -0,0 +1,107 @@
+use indexmap::IndexMap;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    diagnostic::{MustardError, MustardResult},
+    span::SourceSpan,
+};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum StructuredNumber {
+    Finite(f64),
+    NaN,
+    Infinity,
+    NegInfinity,
+    NegZero,
+}
+
+impl StructuredNumber {
+    pub fn from_f64(value: f64) -> Self {
+        if value.is_nan() {
+            Self::NaN
+        } else if value == 0.0f64 && value.is_sign_negative() {
+            Self::NegZero
+        } else if value == f64::INFINITY {
+            Self::Infinity
+        } else if value == f64::NEG_INFINITY {
+            Self::NegInfinity
+        } else {
+            Self::Finite(value)
+        }
+    }
+
+    pub fn to_f64(&self) -> f64 {
+        match self {
+            Self::Finite(value) => *value,
+            Self::NaN => f64::NAN,
+            Self::Infinity => f64::INFINITY,
+            Self::NegInfinity => f64::NEG_INFINITY,
+            Self::NegZero => -0.0,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum StructuredValue {
+    Undefined,
+    Null,
+    Hole,
+    Bool(bool),
+    String(String),
+    Number(StructuredNumber),
+    Array(Vec<StructuredValue>),
+    Object(IndexMap<String, StructuredValue>),
+}
+
+impl StructuredValue {
+    pub fn validate_plain_object(
+        prototype_is_plain: bool,
+        has_accessors: bool,
+        has_cycles: bool,
+        span: Option<SourceSpan>,
+    ) -> MustardResult<()> {
+        if !prototype_is_plain {
+            return Err(MustardError::validation(
+                "host objects with custom prototypes cannot cross the host boundary",
+                span,
+            ));
+        }
+        if has_accessors {
+            return Err(MustardError::validation(
+                "host objects with accessors cannot cross the host boundary",
+                span,
+            ));
+        }
+        if has_cycles {
+            return Err(MustardError::validation(
+                "cyclic values cannot cross the host boundary",
+                span,
+            ));
+        }
+        Ok(())
+    }
+}
+
+impl From<bool> for StructuredValue {
+    fn from(value: bool) -> Self {
+        Self::Bool(value)
+    }
+}
+
+impl From<&str> for StructuredValue {
+    fn from(value: &str) -> Self {
+        Self::String(value.to_string())
+    }
+}
+
+impl From<String> for StructuredValue {
+    fn from(value: String) -> Self {
+        Self::String(value)
+    }
+}
+
+impl From<f64> for StructuredValue {
+    fn from(value: f64) -> Self {
+        Self::Number(StructuredNumber::from_f64(value))
+    }
+}

package/crates/mustard-bridge/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "mustard-bridge"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Shared bridge DTOs and operations for MustardScript adapters"
+
+[dependencies]
+anyhow.workspace = true
+base64 = "0.22.1"
+hmac.workspace = true
+mustard = { path = "../mustard" }
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true

package/crates/mustard-bridge/src/codec.rs

@@ -0,0 +1,46 @@
+use anyhow::Result;
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use mustard::{BytecodeProgram, ExecutionStep, dump_snapshot, load_program};
+use serde::{Serialize, de::DeserializeOwned};
+
+use crate::dto::StepDto;
+
+pub fn parse_json<T: DeserializeOwned>(value: &str) -> Result<T> {
+    serde_json::from_str(value).map_err(Into::into)
+}
+
+pub fn encode_json<T: Serialize>(value: &T) -> Result<String> {
+    serde_json::to_string(value).map_err(Into::into)
+}
+
+pub fn encode_step(step: ExecutionStep) -> Result<StepDto> {
+    Ok(match step {
+        ExecutionStep::Completed(value) => StepDto::Completed { value },
+        ExecutionStep::Suspended(suspension) => StepDto::Suspended {
+            capability: suspension.capability,
+            args: suspension.args,
+            snapshot_base64: STANDARD.encode(dump_snapshot(&suspension.snapshot)?),
+        },
+    })
+}
+
+pub fn encode_step_json(step: ExecutionStep) -> Result<String> {
+    encode_json(&encode_step(step)?)
+}
+
+pub fn decode_program(bytes: &[u8]) -> Result<BytecodeProgram> {
+    load_program(bytes).map_err(Into::into)
+}
+
+pub fn decode_base64(value: &str) -> Result<Vec<u8>> {
+    STANDARD.decode(value).map_err(Into::into)
+}
+
+pub fn decode_program_base64(value: &str) -> Result<BytecodeProgram> {
+    let bytes = decode_base64(value)?;
+    decode_program(&bytes)
+}
+
+pub fn encode_bytes_base64(bytes: &[u8]) -> String {
+    STANDARD.encode(bytes)
+}

package/crates/mustard-bridge/src/dto.rs

@@ -0,0 +1,99 @@
+use std::collections::BTreeMap;
+
+use anyhow::{Result, anyhow};
+use mustard::{HostError, ResumePayload, RuntimeLimits, SnapshotPolicy, StructuredValue};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct StartOptionsDto {
+    #[serde(default)]
+    pub inputs: BTreeMap<String, StructuredValue>,
+    #[serde(default)]
+    pub capabilities: Vec<String>,
+    #[serde(default)]
+    pub limits: RuntimeLimitsDto,
+}
+
+#[derive(Debug, Default, Serialize, Deserialize)]
+pub struct RuntimeLimitsDto {
+    pub instruction_budget: Option<usize>,
+    pub heap_limit_bytes: Option<usize>,
+    pub allocation_budget: Option<usize>,
+    pub call_depth_limit: Option<usize>,
+    pub max_outstanding_host_calls: Option<usize>,
+}
+
+impl RuntimeLimitsDto {
+    pub fn into_runtime_limits(self) -> RuntimeLimits {
+        let defaults = RuntimeLimits::default();
+        RuntimeLimits {
+            instruction_budget: self
+                .instruction_budget
+                .unwrap_or(defaults.instruction_budget),
+            heap_limit_bytes: self.heap_limit_bytes.unwrap_or(defaults.heap_limit_bytes),
+            allocation_budget: self.allocation_budget.unwrap_or(defaults.allocation_budget),
+            call_depth_limit: self.call_depth_limit.unwrap_or(defaults.call_depth_limit),
+            max_outstanding_host_calls: self
+                .max_outstanding_host_calls
+                .unwrap_or(defaults.max_outstanding_host_calls),
+        }
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct SnapshotPolicyDto {
+    #[serde(default)]
+    pub capabilities: Vec<String>,
+    pub limits: Option<RuntimeLimitsDto>,
+    #[serde(default)]
+    pub snapshot_key_base64: Option<String>,
+    #[serde(default)]
+    pub snapshot_token: Option<String>,
+    #[serde(default)]
+    pub snapshot_id: Option<String>,
+    #[serde(default)]
+    pub snapshot_key_digest: Option<String>,
+}
+
+impl SnapshotPolicyDto {
+    pub fn into_snapshot_policy(self) -> Result<SnapshotPolicy> {
+        let limits = self
+            .limits
+            .ok_or_else(|| anyhow!("raw snapshot restore requires explicit limits"))?;
+        Ok(SnapshotPolicy {
+            capabilities: self.capabilities,
+            limits: limits.into_runtime_limits(),
+        })
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum StepDto {
+    Completed {
+        value: StructuredValue,
+    },
+    Suspended {
+        capability: String,
+        args: Vec<StructuredValue>,
+        snapshot_base64: String,
+    },
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ResumeDto {
+    Value { value: StructuredValue },
+    Error { error: HostError },
+    Cancelled,
+}
+
+impl ResumeDto {
+    pub fn into_resume_payload(self) -> ResumePayload {
+        match self {
+            Self::Value { value } => ResumePayload::Value(value),
+            Self::Error { error } => ResumePayload::Error(error),
+            Self::Cancelled => ResumePayload::Cancelled,
+        }
+    }
+}

package/crates/mustard-bridge/src/lib.rs

@@ -0,0 +1,12 @@
+mod codec;
+mod dto;
+mod operations;
+
+pub use codec::{
+    decode_base64, decode_program, decode_program_base64, encode_bytes_base64, encode_json,
+    encode_step, encode_step_json, parse_json,
+};
+pub use dto::{ResumeDto, RuntimeLimitsDto, SnapshotPolicyDto, StartOptionsDto, StepDto};
+pub use operations::{
+    compile_program_bytes, inspect_snapshot_bytes, resume_program, start_program,
+};

package/crates/mustard-bridge/src/operations.rs

@@ -0,0 +1,142 @@
+use anyhow::{Result, anyhow};
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use hmac::{Hmac, Mac};
+use mustard::{
+    BytecodeProgram, CancellationToken, ExecutionOptions, ResumeOptions, SnapshotInspection,
+    compile, dump_program, inspect_snapshot as inspect_loaded_snapshot, load_snapshot,
+    lower_to_bytecode, resume_with_options, start_bytecode,
+};
+use sha2::{Digest, Sha256};
+
+use crate::{
+    codec::encode_step,
+    dto::{ResumeDto, SnapshotPolicyDto, StartOptionsDto, StepDto},
+};
+
+type HmacSha256 = Hmac<Sha256>;
+
+fn snapshot_identity_hex(snapshot: &[u8]) -> String {
+    let digest = Sha256::digest(snapshot);
+    let mut encoded = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut encoded, "{byte:02x}");
+    }
+    encoded
+}
+
+fn snapshot_key_digest_hex(snapshot_key: &[u8]) -> String {
+    let digest = Sha256::digest(snapshot_key);
+    let mut encoded = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut encoded, "{byte:02x}");
+    }
+    encoded
+}
+
+fn encode_snapshot_token(snapshot_id: &str, snapshot_key: &[u8]) -> Result<String> {
+    let mut mac =
+        HmacSha256::new_from_slice(snapshot_key).map_err(|_| anyhow!("invalid snapshot key"))?;
+    mac.update(snapshot_id.as_bytes());
+    let digest = mac.finalize().into_bytes();
+    let mut token = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        use std::fmt::Write as _;
+        let _ = write!(&mut token, "{byte:02x}");
+    }
+    Ok(token)
+}
+
+fn assert_authenticated_snapshot(snapshot_bytes: &[u8], policy: &SnapshotPolicyDto) -> Result<()> {
+    let snapshot_id = policy
+        .snapshot_id
+        .as_deref()
+        .ok_or_else(|| anyhow!("raw snapshot restore requires snapshot_id"))?;
+    let snapshot_key_base64 = policy
+        .snapshot_key_base64
+        .as_deref()
+        .ok_or_else(|| anyhow!("raw snapshot restore requires snapshot_key_base64"))?;
+    let snapshot_token = policy
+        .snapshot_token
+        .as_deref()
+        .ok_or_else(|| anyhow!("raw snapshot restore requires snapshot_token"))?;
+    let snapshot_key_digest = policy
+        .snapshot_key_digest
+        .as_deref()
+        .ok_or_else(|| anyhow!("raw snapshot restore requires snapshot_key_digest"))?;
+    let snapshot_key = STANDARD
+        .decode(snapshot_key_base64)
+        .map_err(|_| anyhow!("snapshot_key_base64 must be valid base64"))?;
+    let expected_snapshot_id = snapshot_identity_hex(snapshot_bytes);
+    if expected_snapshot_id != snapshot_id {
+        return Err(anyhow!(
+            "raw snapshot restore rejected a tampered or unauthenticated snapshot"
+        ));
+    }
+    if snapshot_key_digest_hex(&snapshot_key) != snapshot_key_digest {
+        return Err(anyhow!(
+            "raw snapshot restore rejected a mismatched snapshot key digest"
+        ));
+    }
+    let expected = encode_snapshot_token(snapshot_id, &snapshot_key)?;
+    if expected != snapshot_token {
+        return Err(anyhow!(
+            "raw snapshot restore rejected a tampered or unauthenticated snapshot"
+        ));
+    }
+    Ok(())
+}
+
+pub fn compile_program_bytes(source: &str) -> Result<Vec<u8>> {
+    let parsed = compile(source)?;
+    let bytecode = lower_to_bytecode(&parsed)?;
+    dump_program(&bytecode).map_err(Into::into)
+}
+
+pub fn start_program(
+    program: &BytecodeProgram,
+    options: StartOptionsDto,
+    cancellation_token: Option<CancellationToken>,
+) -> Result<StepDto> {
+    let step = start_bytecode(
+        program,
+        ExecutionOptions {
+            inputs: options.inputs.into_iter().collect(),
+            capabilities: options.capabilities,
+            limits: options.limits.into_runtime_limits(),
+            cancellation_token,
+        },
+    )?;
+    encode_step(step)
+}
+
+pub fn inspect_snapshot_bytes(
+    snapshot_bytes: &[u8],
+    policy: SnapshotPolicyDto,
+) -> Result<SnapshotInspection> {
+    assert_authenticated_snapshot(snapshot_bytes, &policy)?;
+    let mut snapshot = load_snapshot(snapshot_bytes)?;
+    let snapshot_policy = policy.into_snapshot_policy()?;
+    inspect_loaded_snapshot(&mut snapshot, snapshot_policy).map_err(Into::into)
+}
+
+pub fn resume_program(
+    snapshot_bytes: &[u8],
+    payload: ResumeDto,
+    policy: SnapshotPolicyDto,
+    cancellation_token: Option<CancellationToken>,
+) -> Result<StepDto> {
+    assert_authenticated_snapshot(snapshot_bytes, &policy)?;
+    let snapshot = load_snapshot(snapshot_bytes)?;
+    let snapshot_policy = policy.into_snapshot_policy()?;
+    let step = resume_with_options(
+        snapshot,
+        payload.into_resume_payload(),
+        ResumeOptions {
+            cancellation_token,
+            snapshot_policy: Some(snapshot_policy),
+        },
+    )?;
+    encode_step(step)
+}

package/crates/mustard-node/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "mustard-node"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Node-API addon for the MustardScript runtime"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+base64 = "0.22.1"
+mustard = { path = "../mustard" }
+mustard-bridge = { path = "../mustard-bridge" }
+hmac.workspace = true
+napi.workspace = true
+napi-derive.workspace = true
+rand.workspace = true
+sha2.workspace = true
+
+[build-dependencies]
+napi-build = "2.3.1"

package/crates/mustard-node/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}