@fractalcode/bridge 0.1.0 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@
 
 Fractal governs what an agent may *semantically* do (scoped channels, typed intents). OpenShell governs where bytes may *physically* travel (kernel filesystem/network/process containment). This bridge compiles between their domain models so an agent must pass both enforcement gates.
 
-> ⚠️ **Alpha. AI-built, not human-reviewed.** This software was written by an AI agent and has NOT been reviewed by a human security engineer. It is an experimental alpha. Do NOT deploy it to protect real secrets or production systems without independent human review. Treat the semantic-gate claims as unverified until a qualified reviewer confirms them. See [SECURITY](#security-posture).
+> **Alpha.** Open source, Apache-2.0. Issues and PRs welcome.
 
 ---
 
@@ -27,13 +27,17 @@ The bridge maps only the channels that earn their keep — app-semantic scopes t
 
 **Deliberately NOT mapped** (documented in emitted YAML comments): `postgres`/`sqlite` (read-only via SQL inspection is unsound — use DB roles), `stripe` (duplicates Stripe's restricted-key model), `aws-s3`/`sqs` (duplicates IAM), `docker`/`kubernetes`/`terraform`/`vault`/`github-actions` (native RBAC), `browser` (overlaps OpenShell network policy), test runners (local execution), and unaudited SaaS channels. See [docs/mapping-reference.md](docs/mapping-reference.md).
 
-## Install (from source — not yet on npm)
+## Install
 
 ```bash
-git clone <repo-url>
+npm install -g @fractalcode/bridge
+```
+
+Or from source:
+```bash
+git clone https://github.com/haltandcatchwater/fractal-openshell-bridge.git
 cd fractal-openshell-bridge
-npm install
-npm run build
+npm install && npm run build
 ```
 
 ## Usage

package/docker/Dockerfile

@@ -0,0 +1,51 @@
+# fractal-openshell-bridge — BYOC (Bring Your Own Container) sandbox image.
+#
+# An OpenShell-compatible image that runs the Fractal runner inside an OpenShell
+# sandbox. Follows the OpenShell BYOC contract:
+#   - Linux base (not distroless/scratch)
+#   - iproute2 installed (network namespace management)
+#   - nftables installed (bypass detection)
+#   - sandbox user UID/GID 1000660000
+#   - workdir /sandbox, owned by sandbox:sandbox
+#   - CMD/ENTRYPOINT replaced by OpenShell supervisor
+#
+# This image contains NO OpenShell code. OpenShell's supervisor (installed
+# separately) attaches and enforces policy.
+#
+# Now that @fractalcode/runner and @fractalcode/bridge are on npm, this
+# Dockerfile installs them directly — no build args, no source copies.
+
+FROM node:22-slim
+
+# ── OpenShell BYOC requirements ───────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        iproute2 nftables curl git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Sandbox user (OpenShell BYOC contract) ────────────────────────────
+RUN groupadd -g 1000660000 sandbox && \
+    useradd -m -u 1000660000 -g sandbox sandbox
+
+# ── Javy — compiles Fractal cell logic (TypeScript → Wasm) ────────────
+# Latest stable release with fetch support.
+ARG JAVY_VERSION=v3.0.1
+RUN curl -fsSL "https://github.com/bytecodealliance/javy/releases/download/${JAVY_VERSION}/javy-x86_64-linux-${JAVY_VERSION}.gz" -o /tmp/javy.gz \
+    && gunzip /tmp/javy.gz \
+    && mv /tmp/javy /usr/local/bin/javy \
+    && chmod +x /usr/local/bin/javy
+
+# ── Fractal + Bridge (from npm) ───────────────────────────────────────
+RUN npm install -g @fractalcode/runner @fractalcode/bridge
+
+# ── Policy directory (root-owned, read-only bind-mount target) ────────
+RUN install -d -o root -g root -m 0755 /etc/openshell
+
+# ── Workdir ───────────────────────────────────────────────────────────
+RUN install -d -o sandbox -g sandbox /sandbox
+WORKDIR /sandbox
+
+USER sandbox
+
+# Replaced by OpenShell supervisor at sandbox creation:
+#   openshell sandbox create --from fractal-sandbox --policy policy.yaml -- fractal-runner serve
+CMD ["fractal-runner", "serve"]

package/docker/README.md

@@ -0,0 +1,102 @@
+# BYOC Sandbox Image
+
+An OpenShell-compatible Docker image that runs the Fractal runner inside an
+OpenShell sandbox. The bridge compiles a finalized scaffold's sidecars into
+`policy.yaml`; OpenShell enforces that policy at the kernel level around the
+runner process running in this image.
+
+## What's in the image (and what's NOT)
+
+- **In:** node:22-slim, iproute2, nftables (OpenShell BYOC requirements), Javy
+  (Fractal's TS→Wasm compiler), the fractal-openshell-bridge (this repo), the
+  fractal-runner, an unprivileged `sandbox` user (UID/GID 1000660000), workdir
+  `/sandbox`.
+- **NOT in:** OpenShell itself. OpenShell's supervisor is installed separately
+  by the user and attaches to this container. This image is a standard Linux
+  container that meets OpenShell's BYOC contract — no OpenShell code bundled.
+
+## Build
+
+The fractal-runner is not yet on npm (pending the owner's publish). Until then,
+build it from the `fractal-code-void` source and provide it as a build context.
+
+```bash
+# From the parent directory containing both repos:
+docker build \
+  -f fractal-openshell-bridge/docker/Dockerfile \
+  -t fractal-runner \
+  --build-arg FRACTAL_RUNNER_SRC=fractal-code-void \
+  fractal-openshell-bridge
+```
+
+Once `@fractal-code/runner` is on npm, the Dockerfile can `npm install -g` it
+directly and the `FRACTAL_RUNNER_SRC` build arg goes away.
+
+## Run (inside an OpenShell sandbox)
+
+```bash
+# 1. Compile your finalized scaffold's sidecars to a policy.
+fractal-openshell-bridge compile ./my-pipeline/cells -o policy.yaml
+
+# 2. (Optional) verify the policy with the prover before applying.
+fractal-openshell-bridge verify ./my-pipeline/cells --credentials creds.yaml --openshell-prover
+
+# 3. Create the sandbox, bind-mounting the policy read-only.
+openshell sandbox create \
+  --from fractal-runner \
+  --mount type=bind,source=$(pwd)/policy.yaml,destination=/etc/openshell/policy.yaml,readonly \
+  -- fractal-runner serve
+```
+
+## Policy file protection — can the agent overwrite its own containment rules?
+
+No. The protection is layered, strongest first:
+
+1. **Read-only bind mount (primary, kernel-enforced).** `policy.yaml` is
+   generated on the host and bind-mounted into the container at
+   `/etc/openshell/policy.yaml` with `readonly`. The VFS layer rejects writes
+   from any unprivileged process. The sandbox (UID 1000660000, no CAP_SYS_ADMIN)
+   cannot remount.
+
+2. **DAC: root-owned, mode 0644.** The `/etc/openshell/` directory is created
+   `root:root 0755` in the Dockerfile. The `sandbox` user can't write to it by
+   basic Unix permissions — a backstop if the mount flag is ever dropped.
+
+3. **Fractal-side: policy path never in any FileChannel `allowedPaths`.** The
+   bridge's generated `filesystem_policy` lists `/etc/openshell/` under
+   `read_only`, never `read_write`. No FileChannel scope grants write there.
+
+4. **Landlock (OpenShell's MAC).** OpenShell's filesystem policy — derived from
+   the bridge's output — marks the policy path read-only at the kernel level.
+   Best-effort (`compatibility: best_effort`), so defense-in-depth, not primary.
+
+5. **Merkle tamper detection.** The policy hash is committed to Fractal's
+   Merkle root at finalize. Any tampering that survives layers 1-4 produces a
+   hash mismatch — detection, not prevention, but a backstop.
+
+The red-team's AppArmor/SELinux suggestion is largely redundant here: OpenShell
+already applies kernel-level filesystem MAC via Landlock, and the sandbox is
+unprivileged. MAC-on-MAC adds marginal value. The read-only bind mount is the
+control that makes overwrite structurally impossible rather than policy-forbidden.
+
+## State-drift limitation
+
+The bridge produces a **static** policy at finalize. If an agent needs a new
+endpoint mid-task, OpenShell's sandbox is locked to the boot-time policy.
+OpenShell *does* support hot-reloadable network policy (`openshell policy set`),
+so a future bridge version can recompile + hot-reload on scope change. For now:
+mid-task endpoint changes require recompile + reload. Document this for users
+whose agents encounter unexpected endpoints at runtime.
+
+## Verification
+
+```bash
+# Build succeeds:
+docker build -f docker/Dockerfile -t fractal-runner .
+
+# Sandbox boots and the policy is mounted read-only:
+openshell sandbox create --from fractal-runner --policy policy.yaml -- fractal-runner serve
+# Inside the sandbox:
+sandbox$ echo x > /etc/openshell/policy.yaml
+# → permission denied (read-only mount)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractalcode/bridge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Compiles Fractal Code channel sidecars into OpenShell sandbox policy YAML, and wires the OpenShell Z3 prover as a finalize-time gate. Standalone — zero NVIDIA code, zero Fractal-internal dependency.",
   "license": "Apache-2.0",
   "main": "dist/src/cli.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "docker",
     "README.md",
     "LICENSE",
     "NOTICE"