blastbox 0.1.0__py3-none-any.whl

blastbox/__init__.py

@@ -0,0 +1,13 @@
+"""blastbox — reusable detonation framework for untrusted documents.
+
+Engine authors need only the lean core (`pip install blastbox`): implement the
+``Engine`` protocol's ``detonate()`` and return a ``DetonationResult``; the
+host orchestrator (``blastbox[host]``) handles ingress, disposable-worker
+launch, output-trust validation, and serving.
+"""
+from blastbox.worker.engine import DetonationResult, Engine
+from blastbox.worker.harness import run_detonation
+
+__version__ = "0.1.0"
+
+__all__ = ["Engine", "DetonationResult", "run_detonation", "__version__"]

blastbox/contract/__init__.py

@@ -0,0 +1,30 @@
+"""Typed data contract for the detonation framework.
+
+Engines emit a typed payload tree + declared artifacts; the worker SDK seals
+them into an Envelope (hashes, sizes, path-confinement); the host re-validates.
+"""
+from .leaf import Hash, Detection, Warning, ArtifactRef, Dimensions, Lang
+from .nodes import (
+    Record, ExtractedText, Page, EmbeddedResource,
+    parse_node, register_node_type, rebuild_node_union,
+)
+from .envelope import (
+    DeclaredArtifact, Artifact, Envelope,
+    seal_envelope, validate_envelope, envelope_from_json,
+)
+from .walk import iter_nodes, find_by_type
+
+
+def json_schema() -> dict:
+    """Canonical JSON Schema for the Envelope (for non-Python engines)."""
+    return Envelope.model_json_schema()
+
+
+__all__ = [
+    "Hash", "Detection", "Warning", "ArtifactRef", "Dimensions", "Lang",
+    "Record", "ExtractedText", "Page", "EmbeddedResource",
+    "parse_node", "register_node_type", "rebuild_node_union",
+    "DeclaredArtifact", "Artifact", "Envelope",
+    "seal_envelope", "validate_envelope", "envelope_from_json",
+    "iter_nodes", "find_by_type", "json_schema",
+]

blastbox/contract/envelope.py

@@ -0,0 +1,173 @@
+"""The security envelope: sealed by the worker SDK, re-validated by the host."""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .leaf import Detection, Warning
+from .nodes import ChildNode, _REBUILD_CALLBACKS, parse_node
+
+
+class DeclaredArtifact(BaseModel):
+    """What an engine declares; the SDK turns it into a sealed Artifact."""
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    id: str = Field(pattern=r"^[A-Za-z0-9._-]{1,128}$")
+    path: str = Field(max_length=4096)   # outdir-relative
+    kind: str = Field(min_length=1, max_length=64)
+
+
+class Artifact(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    id: str
+    path: str
+    kind: str
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    bytes: int = Field(ge=0)
+
+
+class Envelope(BaseModel):
+    """A signed, sealed, and validated job result envelope.
+
+    The ``payload`` field is typed as ``Annotated[ChildNode, ...]`` at class
+    definition time.  After each ``register_node_type()`` call,
+    ``_rebuild_envelope()`` is triggered via ``nodes._REBUILD_CALLBACKS`` and
+    calls ``Envelope.model_rebuild(force=True, _types_namespace=...)`` so that
+    pydantic re-evaluates the ``"_PayloadNode"`` forward-ref string against the
+    current live union — without any top-level circular import.
+    """
+    model_config = ConfigDict(extra="forbid")
+    engine: str = Field(min_length=1, max_length=64)
+    status: Literal["ok", "rejected", "engine_error"] = "ok"
+    input_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    detected: Detection
+    artifacts: list[Artifact] = Field(default_factory=list)
+    warnings: list[Warning] = Field(default_factory=list)
+    # Initial annotation uses ChildNode (the base union); _rebuild_envelope()
+    # replaces model_fields["payload"].annotation with the live Node union after
+    # each register_node_type() call so engine subtypes are also accepted.
+    payload: Annotated[ChildNode, Field(discriminator="type")]
+
+
+def _rebuild_envelope() -> None:
+    """Rebuild Envelope against the current live Node union.
+
+    Called by nodes.rebuild_node_union() via _REBUILD_CALLBACKS.
+    Uses a lazy import to avoid a circular dependency at module-top level.
+    Updates the ``payload`` field's annotation to the current live ``Node``
+    union so pydantic regenerates the discriminated-union validator correctly.
+    """
+    import blastbox.contract.nodes as _nodes
+    Envelope.model_fields["payload"].annotation = _nodes.Node  # type: ignore[assignment]
+    Envelope.model_rebuild(force=True)
+
+
+# Register so every rebuild_node_union() call (triggered by register_node_type)
+# also refreshes the Envelope discriminated union.
+_REBUILD_CALLBACKS.append(_rebuild_envelope)
+# Apply immediately so the initial union is in place.
+_rebuild_envelope()
+
+
+def _collect_refs(node) -> set[str]:
+    """Walk a node tree and collect every ArtifactRef.id it references."""
+    from .leaf import ArtifactRef as _ArtifactRef
+
+    refs: set[str] = set()
+    stack: list = [node]
+    while stack:
+        v = stack.pop()
+        if isinstance(v, _ArtifactRef):
+            refs.add(v.id)
+        elif isinstance(v, BaseModel):
+            for f in type(v).model_fields:
+                stack.append(getattr(v, f))
+        elif isinstance(v, (list, tuple)):
+            for it in v:
+                stack.append(it)
+        elif isinstance(v, dict):
+            for it in v.values():
+                stack.append(it)
+    return refs
+
+
+def seal_envelope(*, engine: str, outdir: Path, input_sha256: str,
+                  detected: Detection, declared: list[DeclaredArtifact],
+                  warnings: list[Warning], payload: ChildNode,
+                  status: Literal["ok", "rejected", "engine_error"] = "ok") -> Envelope:
+    """Seal declared artifacts + payload into a validated Envelope.
+
+    Computes sha256/bytes from disk, confines every path under outdir, and
+    verifies every ArtifactRef in the payload resolves to a declared id.
+    Raises ValueError on any violation — the worker must not emit on failure.
+    """
+    outdir_resolved = outdir.resolve(strict=False)
+    artifacts: list[Artifact] = []
+    declared_ids: set[str] = set()
+    for d in declared:
+        if d.id in declared_ids:
+            raise ValueError(f"duplicate artifact id: {d.id}")
+        declared_ids.add(d.id)
+        target = (outdir / d.path).resolve(strict=False)
+        if outdir_resolved != target and outdir_resolved not in target.parents:
+            raise ValueError(f"artifact path not confined to outdir: {d.path}")
+        if not target.is_file():
+            raise ValueError(f"declared artifact file missing or not a regular file: {d.path}")
+        data = target.read_bytes()
+        artifacts.append(Artifact(id=d.id, path=d.path, kind=d.kind,
+                                  sha256=hashlib.sha256(data).hexdigest(),
+                                  bytes=len(data)))
+    unresolved = _collect_refs(payload) - declared_ids
+    if unresolved:
+        raise ValueError(f"payload has unresolved ArtifactRef(s): {sorted(unresolved)}")
+    return Envelope(engine=engine, status=status, input_sha256=input_sha256,
+                    detected=detected, artifacts=artifacts, warnings=warnings,
+                    payload=payload)
+
+
+def validate_envelope(env: Envelope, *, outdir: Path, max_artifact_bytes: int,
+                      max_total_bytes: int, max_artifacts: int) -> Envelope:
+    """Host-side re-validation: enforce count/size bounds and verify on-disk sizes.
+
+    Re-stats every artifact file under outdir to confirm st_size matches
+    the declared bytes (so a tampered worker-reported size is caught).
+    Raises ValueError on any violation.
+    """
+    if len(env.artifacts) > max_artifacts:
+        raise ValueError(f"artifact count {len(env.artifacts)} exceeds {max_artifacts}")
+    outdir_resolved = outdir.resolve(strict=False)
+    total = 0
+    for a in env.artifacts:
+        target = (outdir / a.path).resolve(strict=False)
+        if outdir_resolved != target and outdir_resolved not in target.parents:
+            raise ValueError(f"artifact path not confined to outdir: {a.path}")
+        if not target.is_file():
+            raise ValueError(f"artifact file missing or not a regular file: {a.path}")
+        actual_size = target.stat().st_size
+        if actual_size != a.bytes:
+            raise ValueError(
+                f"artifact {a.id} declared bytes={a.bytes} but on-disk size={actual_size}"
+            )
+        if actual_size > max_artifact_bytes:
+            raise ValueError(f"artifact {a.id} bytes {actual_size} exceeds {max_artifact_bytes}")
+        total += actual_size
+    if total > max_total_bytes:
+        raise ValueError(f"total artifact bytes {total} exceeds {max_total_bytes}")
+    return env
+
+
+def envelope_from_json(raw: bytes, *, max_bytes: int = 4 * 1024 * 1024) -> Envelope:
+    """Parse a worker-emitted metadata.json into an Envelope (size-bounded)."""
+    if len(raw) > max_bytes:
+        raise ValueError(f"metadata json {len(raw)} bytes exceeds {max_bytes}")
+    import json
+    obj = json.loads(raw)
+    if not isinstance(obj, dict):
+        raise ValueError("envelope JSON must be a JSON object")
+    payload_data = obj.get("payload")
+    if payload_data is None:
+        raise ValueError("envelope JSON missing required 'payload' field")
+    obj["payload"] = parse_node(payload_data)
+    return Envelope.model_validate(obj)

blastbox/contract/leaf.py

@@ -0,0 +1,68 @@
+"""Leaf types: the shared vocabulary every engine can reuse."""
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_HEX_RE = re.compile(r"\A[0-9a-fA-F]+\Z")
+_SAFE_ID_RE = re.compile(r"\A[A-Za-z0-9._-]{1,128}\Z")
+# Expected hex length per hash algorithm (None = any positive hex length).
+_HASH_HEXLEN: dict[str, int | None] = {
+    "sha256": 64, "phash": 16, "dhash": 16, "ahash": 16, "colorhash": None,
+}
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Hash(_Frozen):
+    algo: Literal["sha256", "phash", "dhash", "ahash", "colorhash"]
+    value: str
+
+    @field_validator("value")
+    @classmethod
+    def _hex(cls, v: str, info) -> str:
+        if not _HEX_RE.match(v):
+            raise ValueError("hash value must be hex")
+        expected = _HASH_HEXLEN.get(info.data.get("algo"))
+        if expected is not None and len(v) != expected:
+            raise ValueError(f"expected {expected} hex chars, got {len(v)}")
+        return v.lower()
+
+
+class ArtifactRef(_Frozen):
+    """A reference into the Envelope's artifact set by id (never a path)."""
+    id: str
+
+    @field_validator("id")
+    @classmethod
+    def _safe(cls, v: str) -> str:
+        if not _SAFE_ID_RE.match(v):
+            raise ValueError("artifact id must match [A-Za-z0-9._-]{1,128}")
+        return v
+
+
+class Detection(_Frozen):
+    label: str = Field(min_length=1, max_length=64)
+    mime: str = Field(max_length=255)
+    confidence: float = Field(ge=0.0, le=1.0)
+    source: str = Field(min_length=1, max_length=32)
+
+
+class Warning(_Frozen):
+    code: str = Field(min_length=1, max_length=64)
+    message: str = Field(max_length=2000)
+    context: str | None = Field(default=None, max_length=255)
+
+
+class Dimensions(_Frozen):
+    width: float = Field(gt=0)
+    height: float = Field(gt=0)
+    unit: Literal["mm", "px", "pt"]
+
+
+class Lang(_Frozen):
+    code: str = Field(min_length=2, max_length=64)

blastbox/contract/nodes.py

@@ -0,0 +1,172 @@
+"""Typed payload nodes: a recursive tree with a generic Record floor."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable, Literal, Union, get_args
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, TypeAdapter
+
+from .leaf import ArtifactRef, Dimensions, Hash, Lang
+
+Scalar = Union[str, int, float, bool, None]
+# A Record field value is a scalar, a list of scalars, or a nested Record.
+RecordValue = Union[Scalar, list[Scalar], "Record"]
+
+
+class _Node(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+def _parse_children(value: Any) -> Any:
+    """Route each child through the *live*, registry-aware node adapter.
+
+    Runs as a ``BeforeValidator`` on the ``children`` fields so that child
+    parsing is decoupled from the static ``ChildNode`` union captured at class
+    definition.  A statically-reassigned union does NOT work here: pydantic
+    bakes a discriminated-union core schema into the ``children`` field when the
+    model is built and does not re-resolve a reassigned module-global union on
+    ``model_rebuild`` — so registered engine subtypes were never reachable as
+    children.  Delegating to ``_NODE_ADAPTER`` (the same adapter ``parse_node``
+    uses, rebuilt by ``rebuild_node_union`` to include engine types) fixes that:
+    the registry is consulted at validation time, not class-definition time.
+
+    Already-constructed ``_Node`` instances pass through untouched; dicts are
+    validated through the live adapter (which rejects unknown ``_type`` and
+    enforces ``extra="forbid"``).  Non-list / non-dict values are returned
+    unchanged so pydantic emits its normal type/length errors.
+    """
+    if not isinstance(value, list):
+        return value
+    if _NODE_ADAPTER is None:
+        rebuild_node_union()
+    assert _NODE_ADAPTER is not None
+    parsed: list[Any] = []
+    for item in value:
+        if isinstance(item, _Node):
+            parsed.append(item)
+        elif isinstance(item, dict):
+            parsed.append(_NODE_ADAPTER.validate_python(item))
+        else:
+            # Let the list[Any] validator surface a normal error for this item.
+            parsed.append(item)
+    return parsed
+
+
+# A children list whose items are parsed by the live registry-aware adapter
+# (via _parse_children) rather than a static union.  Typed list[Any] so pydantic
+# does not re-narrow the already-validated _Node instances back to the 4 base
+# types; max_length is still enforced because BeforeValidator runs first.
+ChildList = Annotated[list[Any], BeforeValidator(_parse_children)]
+
+
+class Record(_Node):
+    """The generic floor: a typed bag for engine data not worth a named type."""
+    type: Literal["record"] = Field(default="record", alias="_type")
+    fields: dict[str, RecordValue] = Field(default_factory=dict, max_length=4096)
+
+
+class ExtractedText(_Node):
+    type: Literal["extracted_text"] = Field(default="extracted_text", alias="_type")
+    text: str = Field(max_length=10_000_000)
+    char_count: int = Field(ge=0)
+    lang: Lang | None = None
+
+
+class Page(_Node):
+    type: Literal["page"] = Field(default="page", alias="_type")
+    index: int = Field(ge=0)
+    dims: Dimensions
+    image: ArtifactRef
+    hashes: list[Hash] = Field(default_factory=list, max_length=32)
+    children: ChildList = Field(default_factory=list, max_length=10000)
+
+
+class EmbeddedResource(_Node):
+    type: Literal["embedded_resource"] = Field(default="embedded_resource", alias="_type")
+    embedded_path: str = Field(max_length=4096)
+    content_type: str = Field(max_length=255)
+    depth: int = Field(ge=0, le=64)
+    metadata: Record | None = None
+    children: ChildList = Field(default_factory=list, max_length=10000)
+
+
+# Forward-declared recursive child union; engine types register into it (Task 4).
+ChildNode = Union[Page, EmbeddedResource, ExtractedText, Record]
+
+# Module-level Node type and adapter; rebuilt by rebuild_node_union().
+Node: Any = Annotated[ChildNode, Field(discriminator="type")]
+_NODE_ADAPTER: TypeAdapter[Any] | None = None
+
+_ENGINE_NODE_TYPES: list[type[_Node]] = []
+
+# Callbacks invoked after every rebuild_node_union() — allows envelope and
+# other modules to re-bind their own models to the live union without
+# introducing a circular top-level import (they register lazily at their
+# own module-init time).
+_REBUILD_CALLBACKS: list[Callable[[], None]] = []
+
+
+def rebuild_node_union() -> None:
+    """(Re)build the discriminated-union adapter. Call after registering types."""
+    global _NODE_ADAPTER, Node
+    members: tuple[type[_Node], ...] = (
+        Page, EmbeddedResource, ExtractedText, Record, *_ENGINE_NODE_TYPES
+    )
+    for m in members:
+        m.model_rebuild()
+    if len(members) > 1:
+        union: Any = Union[members]  # type: ignore[arg-type]
+    else:
+        union = members[0]
+    Node = Annotated[union, Field(discriminator="type")]
+    _NODE_ADAPTER = TypeAdapter(Node)
+    for cb in _REBUILD_CALLBACKS:
+        cb()
+
+
+def parse_node(data: dict[str, Any]) -> ChildNode:
+    """Parse an untyped dict into the correct node by its _type discriminator."""
+    global _NODE_ADAPTER
+    if _NODE_ADAPTER is None:
+        rebuild_node_union()
+    assert _NODE_ADAPTER is not None
+    return _NODE_ADAPTER.validate_python(data)  # type: ignore[return-value]
+
+
+def _discriminator_value(cls: type[_Node]) -> Any:
+    """The Literal discriminator value carried by a node class's ``type`` field."""
+    field = cls.model_fields.get("type")
+    if field is None:
+        return None
+    args = get_args(field.annotation)
+    return args[0] if args else field.default
+
+
+def register_node_type(cls: type[_Node]) -> type[_Node]:
+    """Register an engine-specific node subclass into the parse union.
+
+    The class MUST carry a unique Literal `type` discriminator. After
+    registration the union is rebuilt so parse_node() accepts it.
+
+    Idempotent: re-registering the same class is a no-op, and registering a
+    class whose discriminator value matches an already-registered engine type
+    *replaces* the prior one.  Without the replace, two classes sharing a
+    ``_type`` would both enter the union and pydantic would reject the build
+    with "mapped to multiple choices" — so this keeps the discriminated union
+    well-formed under reloads / duplicate registrations.
+    """
+    if cls in _ENGINE_NODE_TYPES:
+        rebuild_node_union()
+        return cls
+    disc = _discriminator_value(cls)
+    for i, existing in enumerate(_ENGINE_NODE_TYPES):
+        if _discriminator_value(existing) == disc:
+            _ENGINE_NODE_TYPES[i] = cls
+            break
+    else:
+        _ENGINE_NODE_TYPES.append(cls)
+    rebuild_node_union()
+    return cls
+
+
+# Bootstrap: rebuild after all forward refs are defined.
+rebuild_node_union()

blastbox/contract/walk.py

@@ -0,0 +1,35 @@
+"""Generic, engine-agnostic walkers over the typed payload tree."""
+from __future__ import annotations
+
+from typing import Iterator, TypeVar
+
+_T = TypeVar("_T")
+
+_MAX_DEPTH = 128
+
+
+def iter_nodes(root, *, _max_depth: int = _MAX_DEPTH) -> Iterator[object]:
+    """Yield root and every descendant node (pre-order).
+
+    Uses an explicit stack to avoid Python recursion limits.  Raises
+    ``ValueError`` if the tree is deeper than *_max_depth* (default 128)
+    so callers get a clean error instead of a ``RecursionError``.
+    """
+    # Stack entries are (node, depth)
+    stack: list[tuple[object, int]] = [(root, 0)]
+    while stack:
+        node, depth = stack.pop()
+        if depth > _max_depth:
+            raise ValueError(
+                f"payload tree exceeds maximum nesting depth of {_max_depth}"
+            )
+        yield node
+        children = getattr(node, "children", None) or []
+        # Reverse so left-to-right pre-order is preserved when popping.
+        for child in reversed(list(children)):
+            stack.append((child, depth + 1))
+
+
+def find_by_type(root, node_type: type[_T]) -> list[_T]:
+    """All nodes that are instances of node_type (subclasses included)."""
+    return [n for n in iter_nodes(root) if isinstance(n, node_type)]

blastbox/errors.py

@@ -0,0 +1,75 @@
+"""Exception hierarchy for the blastbox framework."""
+
+from __future__ import annotations
+
+import re
+
+
+# Strip internal filesystem paths from public-facing error messages.
+# Root-agnostic: match any absolute POSIX path of two or more segments
+# (``/var/lib/blastbox/x``, ``/etc/passwd``, ``/proc/self/mem``) rather
+# than denylisting specific roots.  A single ``/`` between words (``and/or``)
+# is not a path and is left untouched because it lacks a trailing segment
+# separator.
+_INTERNAL_PATH_RE = re.compile(r"/(?:[A-Za-z0-9._+-]+/)+[A-Za-z0-9._+-]*")
+
+
+def sanitize_public_error(msg: str) -> str:
+    """Remove internal filesystem paths from an error message."""
+    return _INTERNAL_PATH_RE.sub("<path>", msg)
+
+
+class BlastboxError(Exception):
+    """Base for all blastbox errors."""
+
+
+class DetectionError(BlastboxError):
+    """Input was rejected by the detector."""
+
+    def __init__(self, reason: str, detail: str = "") -> None:
+        super().__init__(f"{reason}: {detail}" if detail else reason)
+        self.reason = reason
+        self.detail = detail
+
+
+class SandboxError(BlastboxError):
+    """Sandbox setup or execution failed."""
+
+
+class SandboxTimeout(SandboxError):
+    """Sandboxed process exceeded the wall-clock timeout."""
+
+
+class SandboxUnavailable(SandboxError):
+    """No usable sandbox backend on this host."""
+
+
+class EngineError(BlastboxError):
+    """An engine-specific failure (e.g. LibreOffice, Tika, …)."""
+
+
+class DetonationError(BlastboxError):
+    """Top-level detonation failure, optionally wrapping a cause."""
+
+    def __init__(self, message: str, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+        if cause is not None:
+            self.__cause__ = cause
+
+
+# Keep ConversionError as an alias so engines can use the familiar name
+# without importing engine-specific terms into the generic layer.
+ConversionError = DetonationError
+
+
+class ValidationError(BlastboxError):
+    """Envelope / metadata validation failed."""
+
+
+class OutputTrustError(BlastboxError):
+    """Worker output failed the host-side trust validation."""
+
+
+class WarmTimeout(BlastboxError):
+    """No job arrived within the idle-timeout window for a warm worker slot."""