blastbox 0.1.0__tar.gz

blastbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Metcalf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blastbox-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: blastbox
+Version: 0.1.0
+Summary: Reusable detonation framework: run untrusted documents through disposable, hardened workers
+Author: Will Metcalf
+License: MIT
+Project-URL: Homepage, https://github.com/wmetcalf/blastbox
+Project-URL: Repository, https://github.com/wmetcalf/blastbox
+Project-URL: Issues, https://github.com/wmetcalf/blastbox/issues
+Keywords: sandbox,malware,detonation,untrusted,document,isolation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6.0
+Provides-Extra: host
+Requires-Dist: fastapi>=0.110; extra == "host"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "host"
+Requires-Dist: python-multipart>=0.0.9; extra == "host"
+Requires-Dist: structlog>=24.1; extra == "host"
+Requires-Dist: prometheus-client>=0.20; extra == "host"
+Requires-Dist: psycopg[binary]>=3.2; extra == "host"
+Requires-Dist: redis>=5.0; extra == "host"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: fakeredis>=2.21; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# blastbox
+
+**A reusable framework for running untrusted/malicious documents through disposable, hardened
+workers** — and turning their output into a typed, host-validated result you can trust.
+
+Extracted from the common substrate of two production services (a LibreOffice document→image
+rasterizer and a Tika recursive-extraction service) that had each grown a parallel, drifting copy of
+the same machinery. blastbox is the single, audited-once core; each service becomes a thin *engine*.
+
+- **Write one function.** An engine implements `detonate(input, outdir, limits) -> DetonationResult`.
+  The framework gives it ingress, a JobStore, a disposable hardened worker per job, output-trust
+  validation, artifact serving, optional warm pooling, metrics, and a CLI — for free.
+- **Output is never trusted.** A worker processes a malicious document; the host **re-seals its
+  output from disk** (recomputing hashes/sizes, confining paths) before believing a byte of it.
+- **One untrusted doc per disposable slot** — always. Warm pooling pre-pays startup in the
+  background; it never reuses a worker across documents.
+- **Typed, engine-shaped output.** A shared node library (`Page`, `EmbeddedResource`, `ExtractedText`,
+  a generic `Record` floor, recursive) lets engines be as specific or generic as they need, while the
+  framework validates a fixed security envelope identically for everyone.
+
+Proven end-to-end against two real, language-diverse engines: a **Python + LibreOffice** rasterizer
+and a **JVM + Tika** recursive extractor.
+
+## Architecture
+
+```
+blastbox/
+├── contract/   typed node tree + security envelope + seal/validate (registry-aware at any depth)
+├── host/       LAYER 1 — host orchestrator (engine-agnostic) — needs blastbox[host]
+│   ├── ingress     FastAPI API + CLI: upload, status, artifact serving, /metrics
+│   ├── jobs/       JobStore protocol + memory / sql / redis backends + retention
+│   ├── dispatch    claim → launch disposable worker → validate output → serve   (+ warm path)
+│   ├── runtime/    runc/runsc selection (fail-closed) + hardened worker `docker run` argv
+│   ├── pool        warm slot pool (one-doc-per-slot, never-reuse)
+│   ├── trust       output-trust validator — re-seals worker output from disk
+│   └── observability
+└── worker/     LAYER 2 — worker SDK (runs inside the disposable worker) — lean core
+    ├── engine      the seam: detect / warmup / detonate
+    ├── harness     read input → detonate → seal → write metadata.json
+    ├── sandbox/    in-process hardening self-check + env-stripped subprocess execution
+    └── warm        service lifecycle: boot → warmup → one job → exit
+```
+
+The host never imports an engine; it depends only on the **contract**. An engine never handles
+hashes/paths defensively; the worker SDK and host do that in audited code.
+
+## Writing an engine
+
+```python
+from pathlib import Path
+from blastbox import Engine, DetonationResult, run_detonation
+from blastbox.contract import Page, DeclaredArtifact, Detection, ArtifactRef, Dimensions
+from blastbox.limits import Limits
+
+class MyEngine:
+    name = "myengine"
+    formats = frozenset({"pdf"})
+
+    def detonate(self, input: Path, outdir: Path, limits: Limits) -> DetonationResult:
+        # ... render/extract; write artifact files into outdir ...
+        (outdir / "page-001.png").write_bytes(png_bytes)
+        return DetonationResult(
+            payload=Page(index=0, dims=Dimensions(width=210, height=297, unit="mm"),
+                         image=ArtifactRef(id="p0")),
+            artifacts=[DeclaredArtifact(id="p0", path="page-001.png", kind="image")],
+            detected=Detection(label="pdf", mime="application/pdf", confidence=1.0, source="myengine"),
+        )
+
+# worker entrypoint:
+if __name__ == "__main__":
+    import sys
+    from blastbox.worker.harness import main
+    sys.exit(main(MyEngine()))
+```
+
+The harness seals your declared artifacts (recomputing sha256/size from disk, confining paths,
+resolving references) and writes `metadata.json`. The host's `validate_worker_output` re-validates it.
+Complex engines build recursive `EmbeddedResource` trees (e.g. Tika's recursive metadata); simple
+ones use `Page`/`Record`. Engine-specific node subtypes register via `contract.register_node_type`.
+
+## Install
+
+```sh
+pip install blastbox           # lean core — everything an ENGINE needs (pydantic only)
+pip install blastbox[host]     # + the host orchestrator (FastAPI, jobstores, observability)
+```
+
+## Run (host)
+
+```sh
+blastbox serve     --host 127.0.0.1 --port 8000     # the ingress API
+blastbox dispatch                                    # the worker dispatcher loop
+```
+
+`POST /v1/jobs` (multipart `file` + `engine`) enqueues a job; the dispatcher launches a hardened
+disposable worker for it; `GET /v1/jobs/{id}/artifacts/{artifact_id}` serves validated output.
+
+## Security model
+
+- Disposable worker per job: `--network=none --cap-drop=ALL --no-new-privileges --read-only`, runsc
+  preferred (fail-closed when a secure runtime is required); the input is deleted after conversion.
+- The host re-seals worker output from disk — worker-reported hashes/sizes are never trusted; artifact
+  paths are confined; the input-SHA round-trip is checked; `metadata.json` must be a regular file.
+- Ingress rejects oversized bodies before spooling, sanitizes filenames, serves artifacts by id under
+  a confined path, and (optionally) sits behind a bearer token / auth proxy.
+- The contract bounds payload size/depth and validates every node; engine subtypes are validated
+  against their registered schema.
+
+## Status
+
+Core framework complete and adversarially tested: contract + full host orchestrator + worker SDK
+(harness, container sandbox, warm protocol) + warm pool + warm dispatch. Proven end-to-end on two real
+engines.
+
+Roadmap: host-native `bwrap`/`nsjail` sandbox backends; Firecracker microVM + snapshot runtime; the
+warm-pool burst/health loops.
+
+## License
+
+MIT.

blastbox-0.1.0/README.md

@@ -0,0 +1,120 @@
+# blastbox
+
+**A reusable framework for running untrusted/malicious documents through disposable, hardened
+workers** — and turning their output into a typed, host-validated result you can trust.
+
+Extracted from the common substrate of two production services (a LibreOffice document→image
+rasterizer and a Tika recursive-extraction service) that had each grown a parallel, drifting copy of
+the same machinery. blastbox is the single, audited-once core; each service becomes a thin *engine*.
+
+- **Write one function.** An engine implements `detonate(input, outdir, limits) -> DetonationResult`.
+  The framework gives it ingress, a JobStore, a disposable hardened worker per job, output-trust
+  validation, artifact serving, optional warm pooling, metrics, and a CLI — for free.
+- **Output is never trusted.** A worker processes a malicious document; the host **re-seals its
+  output from disk** (recomputing hashes/sizes, confining paths) before believing a byte of it.
+- **One untrusted doc per disposable slot** — always. Warm pooling pre-pays startup in the
+  background; it never reuses a worker across documents.
+- **Typed, engine-shaped output.** A shared node library (`Page`, `EmbeddedResource`, `ExtractedText`,
+  a generic `Record` floor, recursive) lets engines be as specific or generic as they need, while the
+  framework validates a fixed security envelope identically for everyone.
+
+Proven end-to-end against two real, language-diverse engines: a **Python + LibreOffice** rasterizer
+and a **JVM + Tika** recursive extractor.
+
+## Architecture
+
+```
+blastbox/
+├── contract/   typed node tree + security envelope + seal/validate (registry-aware at any depth)
+├── host/       LAYER 1 — host orchestrator (engine-agnostic) — needs blastbox[host]
+│   ├── ingress     FastAPI API + CLI: upload, status, artifact serving, /metrics
+│   ├── jobs/       JobStore protocol + memory / sql / redis backends + retention
+│   ├── dispatch    claim → launch disposable worker → validate output → serve   (+ warm path)
+│   ├── runtime/    runc/runsc selection (fail-closed) + hardened worker `docker run` argv
+│   ├── pool        warm slot pool (one-doc-per-slot, never-reuse)
+│   ├── trust       output-trust validator — re-seals worker output from disk
+│   └── observability
+└── worker/     LAYER 2 — worker SDK (runs inside the disposable worker) — lean core
+    ├── engine      the seam: detect / warmup / detonate
+    ├── harness     read input → detonate → seal → write metadata.json
+    ├── sandbox/    in-process hardening self-check + env-stripped subprocess execution
+    └── warm        service lifecycle: boot → warmup → one job → exit
+```
+
+The host never imports an engine; it depends only on the **contract**. An engine never handles
+hashes/paths defensively; the worker SDK and host do that in audited code.
+
+## Writing an engine
+
+```python
+from pathlib import Path
+from blastbox import Engine, DetonationResult, run_detonation
+from blastbox.contract import Page, DeclaredArtifact, Detection, ArtifactRef, Dimensions
+from blastbox.limits import Limits
+
+class MyEngine:
+    name = "myengine"
+    formats = frozenset({"pdf"})
+
+    def detonate(self, input: Path, outdir: Path, limits: Limits) -> DetonationResult:
+        # ... render/extract; write artifact files into outdir ...
+        (outdir / "page-001.png").write_bytes(png_bytes)
+        return DetonationResult(
+            payload=Page(index=0, dims=Dimensions(width=210, height=297, unit="mm"),
+                         image=ArtifactRef(id="p0")),
+            artifacts=[DeclaredArtifact(id="p0", path="page-001.png", kind="image")],
+            detected=Detection(label="pdf", mime="application/pdf", confidence=1.0, source="myengine"),
+        )
+
+# worker entrypoint:
+if __name__ == "__main__":
+    import sys
+    from blastbox.worker.harness import main
+    sys.exit(main(MyEngine()))
+```
+
+The harness seals your declared artifacts (recomputing sha256/size from disk, confining paths,
+resolving references) and writes `metadata.json`. The host's `validate_worker_output` re-validates it.
+Complex engines build recursive `EmbeddedResource` trees (e.g. Tika's recursive metadata); simple
+ones use `Page`/`Record`. Engine-specific node subtypes register via `contract.register_node_type`.
+
+## Install
+
+```sh
+pip install blastbox           # lean core — everything an ENGINE needs (pydantic only)
+pip install blastbox[host]     # + the host orchestrator (FastAPI, jobstores, observability)
+```
+
+## Run (host)
+
+```sh
+blastbox serve     --host 127.0.0.1 --port 8000     # the ingress API
+blastbox dispatch                                    # the worker dispatcher loop
+```
+
+`POST /v1/jobs` (multipart `file` + `engine`) enqueues a job; the dispatcher launches a hardened
+disposable worker for it; `GET /v1/jobs/{id}/artifacts/{artifact_id}` serves validated output.
+
+## Security model
+
+- Disposable worker per job: `--network=none --cap-drop=ALL --no-new-privileges --read-only`, runsc
+  preferred (fail-closed when a secure runtime is required); the input is deleted after conversion.
+- The host re-seals worker output from disk — worker-reported hashes/sizes are never trusted; artifact
+  paths are confined; the input-SHA round-trip is checked; `metadata.json` must be a regular file.
+- Ingress rejects oversized bodies before spooling, sanitizes filenames, serves artifacts by id under
+  a confined path, and (optionally) sits behind a bearer token / auth proxy.
+- The contract bounds payload size/depth and validates every node; engine subtypes are validated
+  against their registered schema.
+
+## Status
+
+Core framework complete and adversarially tested: contract + full host orchestrator + worker SDK
+(harness, container sandbox, warm protocol) + warm pool + warm dispatch. Proven end-to-end on two real
+engines.
+
+Roadmap: host-native `bwrap`/`nsjail` sandbox backends; Firecracker microVM + snapshot runtime; the
+warm-pool burst/health loops.
+
+## License
+
+MIT.

blastbox-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blastbox"
+version = "0.1.0"
+description = "Reusable detonation framework: run untrusted documents through disposable, hardened workers"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Will Metcalf" }]
+keywords = ["sandbox", "malware", "detonation", "untrusted", "document", "isolation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+# Core depends on pydantic ONLY. This is everything an *engine* needs — the
+# typed contract + the worker SDK (engine seam, harness, sandbox, warm
+# protocol). An engine adapter installs `blastbox` and stays lean.
+dependencies = [
+    "pydantic>=2.6.0",
+]
+
+[project.optional-dependencies]
+# The host orchestrator (ingress API + CLI, dispatcher, pool, runtime,
+# jobstores, observability). A host deployment installs `blastbox[host]`.
+host = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "python-multipart>=0.0.9",
+    "structlog>=24.1",
+    "prometheus-client>=0.20",
+    "psycopg[binary]>=3.2",
+    "redis>=5.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "mypy>=1.9.0",
+    "ruff>=0.3.0",
+    "fakeredis>=2.21",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/wmetcalf/blastbox"
+Repository = "https://github.com/wmetcalf/blastbox"
+Issues = "https://github.com/wmetcalf/blastbox/issues"
+
+[project.scripts]
+blastbox = "blastbox.host.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra -q"

blastbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blastbox-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)