mustardscript 0.1.0

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Scope
+
+Security issues include:
+
+- Guest escapes from the intended language boundary
+- Host value validation failures that permit unsafe object transfer
+- Snapshot or sidecar deserialization bugs
+- Limit enforcement bugs that break documented containment guarantees
+
+## Important Notes
+
+- Addon mode is not a hard isolation boundary.
+- Sidecar mode is stronger, but hostile deployments still require OS-level controls.
+
+## Reporting
+
+Report vulnerabilities through GitHub Security Advisories:
+
+- https://github.com/keppoai/mustardscript/security/advisories/new
+
+Do not open public GitHub issues for unpatched security reports.
+
+## Supported Versions
+
+- The latest published npm release
+- `main` before the next release is cut
+
+## Response Expectations
+
+- Initial triage acknowledgment target: 5 business days
+- Coordinated disclosure and fix timing will be handled through the advisory
+  thread

package/crates/mustard/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "mustard"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Sandboxed subset-JavaScript runtime core for MustardScript"
+
+[dependencies]
+anyhow.workspace = true
+bincode.workspace = true
+futures.workspace = true
+indexmap.workspace = true
+num-bigint.workspace = true
+num-traits.workspace = true
+oxc_allocator.workspace = true
+oxc_ast.workspace = true
+oxc_parser.workspace = true
+oxc_span.workspace = true
+oxc_syntax.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+slotmap.workspace = true
+thiserror.workspace = true
+regex.workspace = true
+rand.workspace = true
+time.workspace = true
+
+[dev-dependencies]
+proptest = "1.9.0"

package/crates/mustard/src/cancellation.rs

@@ -0,0 +1,28 @@
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
+
+#[derive(Debug, Clone, Default)]
+pub struct CancellationToken {
+    state: Arc<AtomicBool>,
+}
+
+impl CancellationToken {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn cancel(&self) {
+        self.state.store(true, Ordering::SeqCst);
+    }
+
+    pub fn is_cancelled(&self) -> bool {
+        self.state.load(Ordering::SeqCst)
+    }
+
+    #[doc(hidden)]
+    pub fn from_shared(state: Arc<AtomicBool>) -> Self {
+        Self { state }
+    }
+}

package/crates/mustard/src/diagnostic.rs

@@ -0,0 +1,145 @@
+use std::fmt;
+
+use crate::span::SourceSpan;
+
+pub type MustardResult<T> = Result<T, MustardError>;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DiagnosticKind {
+    Parse,
+    Validation,
+    Runtime,
+    Limit,
+    Serialization,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Diagnostic {
+    pub kind: DiagnosticKind,
+    pub message: String,
+    pub span: Option<SourceSpan>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TraceFrame {
+    pub function_name: Option<String>,
+    pub span: SourceSpan,
+}
+
+impl Diagnostic {
+    pub fn parse(message: impl Into<String>, span: Option<SourceSpan>) -> Self {
+        Self {
+            kind: DiagnosticKind::Parse,
+            message: message.into(),
+            span,
+        }
+    }
+
+    pub fn validation(message: impl Into<String>, span: Option<SourceSpan>) -> Self {
+        Self {
+            kind: DiagnosticKind::Validation,
+            message: message.into(),
+            span,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum MustardError {
+    Diagnostics(Vec<Diagnostic>),
+    Message {
+        kind: DiagnosticKind,
+        message: String,
+        span: Option<SourceSpan>,
+        traceback: Vec<TraceFrame>,
+    },
+}
+
+impl MustardError {
+    pub fn validation(message: impl Into<String>, span: Option<SourceSpan>) -> Self {
+        Self::Message {
+            kind: DiagnosticKind::Validation,
+            message: message.into(),
+            span,
+            traceback: Vec::new(),
+        }
+    }
+
+    pub fn runtime(message: impl Into<String>) -> Self {
+        Self::Message {
+            kind: DiagnosticKind::Runtime,
+            message: message.into(),
+            span: None,
+            traceback: Vec::new(),
+        }
+    }
+
+    pub fn runtime_at(message: impl Into<String>, span: SourceSpan) -> Self {
+        Self::Message {
+            kind: DiagnosticKind::Runtime,
+            message: message.into(),
+            span: Some(span),
+            traceback: Vec::new(),
+        }
+    }
+
+    pub fn with_traceback(mut self, frames: Vec<TraceFrame>) -> Self {
+        if frames.is_empty() {
+            return self;
+        }
+        if let Self::Message {
+            span, traceback, ..
+        } = &mut self
+        {
+            if span.is_none() {
+                *span = frames.first().map(|frame| frame.span);
+            }
+            if traceback.is_empty() {
+                *traceback = frames;
+            }
+        }
+        self
+    }
+}
+
+impl fmt::Display for MustardError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Diagnostics(items) => {
+                for (index, item) in items.iter().enumerate() {
+                    if index > 0 {
+                        writeln!(f)?;
+                    }
+                    write!(f, "{:?}: {}", item.kind, item.message)?;
+                    if let Some(span) = item.span {
+                        write!(f, " [{}..{}]", span.start, span.end)?;
+                    }
+                }
+                Ok(())
+            }
+            Self::Message {
+                kind,
+                message,
+                span,
+                traceback,
+            } => {
+                write!(f, "{kind:?}: {message}")?;
+                if let Some(span) = span {
+                    write!(f, " [{}..{}]", span.start, span.end)?;
+                }
+                for frame in traceback {
+                    write!(
+                        f,
+                        "\n  at {} [{}..{}]",
+                        frame.function_name.as_deref().unwrap_or("<script>"),
+                        frame.span.start,
+                        frame.span.end
+                    )?;
+                }
+                Ok(())
+            }
+        }
+    }
+}
+
+impl std::error::Error for MustardError {}

package/crates/mustard/src/ir.rs

@@ -0,0 +1,435 @@
+use serde::{Deserialize, Serialize};
+
+use crate::span::SourceSpan;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CompiledProgram {
+    pub source: String,
+    pub script: Script,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Script {
+    pub span: SourceSpan,
+    pub body: Vec<Stmt>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum Stmt {
+    Block {
+        span: SourceSpan,
+        body: Vec<Stmt>,
+    },
+    VariableDecl {
+        span: SourceSpan,
+        kind: BindingKind,
+        declarators: Vec<Declarator>,
+    },
+    FunctionDecl {
+        span: SourceSpan,
+        function: FunctionExpr,
+    },
+    Expression {
+        span: SourceSpan,
+        expression: Expr,
+    },
+    If {
+        span: SourceSpan,
+        test: Expr,
+        consequent: Box<Stmt>,
+        alternate: Option<Box<Stmt>>,
+    },
+    While {
+        span: SourceSpan,
+        test: Expr,
+        body: Box<Stmt>,
+    },
+    DoWhile {
+        span: SourceSpan,
+        body: Box<Stmt>,
+        test: Expr,
+    },
+    For {
+        span: SourceSpan,
+        init: Option<ForInit>,
+        test: Option<Expr>,
+        update: Option<Expr>,
+        body: Box<Stmt>,
+    },
+    ForOf {
+        span: SourceSpan,
+        await_each: bool,
+        head: ForOfHead,
+        iterable: Expr,
+        body: Box<Stmt>,
+    },
+    ForIn {
+        span: SourceSpan,
+        head: ForOfHead,
+        object: Expr,
+        body: Box<Stmt>,
+    },
+    Break {
+        span: SourceSpan,
+    },
+    Continue {
+        span: SourceSpan,
+    },
+    Return {
+        span: SourceSpan,
+        value: Option<Expr>,
+    },
+    Throw {
+        span: SourceSpan,
+        value: Expr,
+    },
+    Try {
+        span: SourceSpan,
+        body: Box<Stmt>,
+        catch: Option<CatchClause>,
+        finally: Option<Box<Stmt>>,
+    },
+    Switch {
+        span: SourceSpan,
+        discriminant: Expr,
+        cases: Vec<SwitchCase>,
+    },
+    Empty {
+        span: SourceSpan,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ForInit {
+    VariableDecl {
+        kind: BindingKind,
+        declarators: Vec<Declarator>,
+    },
+    Expression(Expr),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ForOfHead {
+    Binding { kind: BindingKind, pattern: Pattern },
+    Assignment { target: AssignTarget },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Declarator {
+    pub span: SourceSpan,
+    pub pattern: Pattern,
+    pub initializer: Option<Expr>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BindingKind {
+    Let,
+    Const,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CatchClause {
+    pub span: SourceSpan,
+    pub parameter: Option<Pattern>,
+    pub body: Box<Stmt>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SwitchCase {
+    pub span: SourceSpan,
+    pub test: Option<Expr>,
+    pub consequent: Vec<Stmt>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum Pattern {
+    Identifier {
+        span: SourceSpan,
+        name: String,
+    },
+    Object {
+        span: SourceSpan,
+        properties: Vec<ObjectPatternProperty>,
+        rest: Option<Box<Pattern>>,
+    },
+    Array {
+        span: SourceSpan,
+        elements: Vec<Option<Pattern>>,
+        rest: Option<Box<Pattern>>,
+    },
+    Default {
+        span: SourceSpan,
+        target: Box<Pattern>,
+        default_value: Expr,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ObjectPatternProperty {
+    pub span: SourceSpan,
+    pub key: PropertyName,
+    pub value: Pattern,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum PropertyName {
+    Identifier(String),
+    String(String),
+    Number(f64),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FunctionExpr {
+    pub span: SourceSpan,
+    pub name: Option<String>,
+    pub length: usize,
+    pub display_source: String,
+    pub params: Vec<Pattern>,
+    pub rest: Option<Pattern>,
+    pub param_init: Vec<Stmt>,
+    pub body: Vec<Stmt>,
+    pub is_async: bool,
+    pub is_arrow: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum Expr {
+    Undefined {
+        span: SourceSpan,
+    },
+    Null {
+        span: SourceSpan,
+    },
+    Bool {
+        span: SourceSpan,
+        value: bool,
+    },
+    Number {
+        span: SourceSpan,
+        value: f64,
+    },
+    BigInt {
+        span: SourceSpan,
+        value: String,
+    },
+    String {
+        span: SourceSpan,
+        value: String,
+    },
+    RegExp {
+        span: SourceSpan,
+        pattern: String,
+        flags: String,
+    },
+    Identifier {
+        span: SourceSpan,
+        name: String,
+    },
+    This {
+        span: SourceSpan,
+    },
+    Array {
+        span: SourceSpan,
+        elements: Vec<ArrayElement>,
+    },
+    Object {
+        span: SourceSpan,
+        properties: Vec<ObjectProperty>,
+    },
+    Function(Box<FunctionExpr>),
+    Unary {
+        span: SourceSpan,
+        operator: UnaryOp,
+        argument: Box<Expr>,
+    },
+    Binary {
+        span: SourceSpan,
+        operator: BinaryOp,
+        left: Box<Expr>,
+        right: Box<Expr>,
+    },
+    Sequence {
+        span: SourceSpan,
+        expressions: Vec<Expr>,
+    },
+    Logical {
+        span: SourceSpan,
+        operator: LogicalOp,
+        left: Box<Expr>,
+        right: Box<Expr>,
+    },
+    Conditional {
+        span: SourceSpan,
+        test: Box<Expr>,
+        consequent: Box<Expr>,
+        alternate: Box<Expr>,
+    },
+    Assignment {
+        span: SourceSpan,
+        target: Box<AssignTarget>,
+        operator: AssignOp,
+        value: Box<Expr>,
+    },
+    Update {
+        span: SourceSpan,
+        target: Box<AssignTarget>,
+        operator: UpdateOp,
+        prefix: bool,
+    },
+    Member {
+        span: SourceSpan,
+        object: Box<Expr>,
+        property: MemberProperty,
+        optional: bool,
+    },
+    Call {
+        span: SourceSpan,
+        callee: Box<Expr>,
+        arguments: Vec<CallArgument>,
+        optional: bool,
+    },
+    New {
+        span: SourceSpan,
+        callee: Box<Expr>,
+        arguments: Vec<CallArgument>,
+    },
+    Template {
+        span: SourceSpan,
+        quasis: Vec<String>,
+        expressions: Vec<Expr>,
+    },
+    Await {
+        span: SourceSpan,
+        value: Box<Expr>,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ArrayElement {
+    Value(Expr),
+    Hole { span: SourceSpan },
+    Spread { span: SourceSpan, value: Expr },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ObjectProperty {
+    Property {
+        span: SourceSpan,
+        key: ObjectPropertyKey,
+        value: Expr,
+    },
+    Spread {
+        span: SourceSpan,
+        value: Expr,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ObjectPropertyKey {
+    Static(PropertyName),
+    Computed(Box<Expr>),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum MemberProperty {
+    Static(PropertyName),
+    Computed(Box<Expr>),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum CallArgument {
+    Value(Expr),
+    Spread { span: SourceSpan, value: Expr },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum AssignTarget {
+    Identifier {
+        span: SourceSpan,
+        name: String,
+    },
+    Member {
+        span: SourceSpan,
+        object: Box<Expr>,
+        property: MemberProperty,
+        optional: bool,
+    },
+    Array {
+        span: SourceSpan,
+        elements: Vec<Option<AssignTarget>>,
+        rest: Option<Box<AssignTarget>>,
+    },
+    Object {
+        span: SourceSpan,
+        properties: Vec<AssignTargetProperty>,
+        rest: Option<Box<AssignTarget>>,
+    },
+    Default {
+        span: SourceSpan,
+        target: Box<AssignTarget>,
+        default_value: Box<Expr>,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AssignTargetProperty {
+    pub span: SourceSpan,
+    pub key: PropertyName,
+    pub value: AssignTarget,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum UpdateOp {
+    Increment,
+    Decrement,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum UnaryOp {
+    Plus,
+    Minus,
+    Not,
+    Typeof,
+    Void,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BinaryOp {
+    Add,
+    Sub,
+    Mul,
+    Div,
+    Rem,
+    Pow,
+    In,
+    Instanceof,
+    Eq,
+    NotEq,
+    StrictEq,
+    StrictNotEq,
+    LessThan,
+    LessThanEq,
+    GreaterThan,
+    GreaterThanEq,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum LogicalOp {
+    And,
+    Or,
+    NullishCoalesce,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AssignOp {
+    Assign,
+    AddAssign,
+    SubAssign,
+    MulAssign,
+    DivAssign,
+    RemAssign,
+    PowAssign,
+    OrAssign,
+    AndAssign,
+    NullishAssign,
+}

package/crates/mustard/src/lib.rs

@@ -0,0 +1,21 @@
+pub mod cancellation;
+pub mod diagnostic;
+pub mod ir;
+pub mod limits;
+pub mod parser;
+pub mod runtime;
+pub mod span;
+pub mod structured;
+
+pub use cancellation::CancellationToken;
+pub use diagnostic::{Diagnostic, DiagnosticKind, MustardError, MustardResult};
+pub use ir::CompiledProgram;
+pub use limits::RuntimeLimits;
+pub use parser::compile;
+pub use runtime::{
+    BytecodeProgram, ExecutionOptions, ExecutionSnapshot, ExecutionStep, HostError, ResumeOptions,
+    ResumePayload, SnapshotInspection, SnapshotPolicy, Suspension, canonical_snapshot_auth_bytes,
+    dump_program, dump_snapshot, execute, inspect_snapshot, load_program, load_snapshot,
+    lower_to_bytecode, resume, resume_with_options, start, start_bytecode,
+};
+pub use structured::StructuredValue;

package/crates/mustard/src/limits.rs

@@ -0,0 +1,22 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct RuntimeLimits {
+    pub instruction_budget: usize,
+    pub heap_limit_bytes: usize,
+    pub allocation_budget: usize,
+    pub call_depth_limit: usize,
+    pub max_outstanding_host_calls: usize,
+}
+
+impl Default for RuntimeLimits {
+    fn default() -> Self {
+        Self {
+            instruction_budget: 1_000_000,
+            heap_limit_bytes: 8 * 1024 * 1024,
+            allocation_budget: 250_000,
+            call_depth_limit: 256,
+            max_outstanding_host_calls: 128,
+        }
+    }
+}