fractal-openshell-bridge

Compiles Fractal Code channel sidecars into OpenShell sandbox policy YAML, and wires the OpenShell Z3 prover as a finalize-time gate.

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. Open source, Apache-2.0. Issues and PRs welcome.

What it does

• compile — reads a directory of Fractal .channels.json sidecars, emits OpenShell policy.yaml. A pure, deterministic function: identical input → byte-identical output → identical SHA-256 hash.
• prove — invokes openshell-prover as a subprocess against a compiled policy + credentials, returns structured findings. Fail-closed if the prover is flagged-on but absent or crashing.
• verify — compile + prove in one step. Intended as a finalize-time gate: a pipeline that would leak data through a misconfigured channel is rejected before it can execute.

Channel scope (keepers only)

The bridge maps only the channels that earn their keep — app-semantic scopes the platform can't enforce natively:

| Fractal kind | Maps to | |---|---| | file | filesystem_policy (read_write / read_only) | | http | network_policies (host + L7 method rules) | | anthropic / openai / google-genai / cohere / mistral | network_policies (provider API host) | | github | network_policies (api.github.com + L7 method/path rules from allowedOperations) |

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.

Install

npm install -g @fractalcode/bridge

Or from source:

git clone https://github.com/haltandcatchwater/fractal-openshell-bridge.git
cd fractal-openshell-bridge
npm install && npm run build

Usage

# Compile a finalized scaffold's sidecars into OpenShell policy
fractal-openshell-bridge compile ./my-pipeline/cells -o policy.yaml

# Run the prover against the compiled policy
fractal-openshell-bridge prove --policy policy.yaml --credentials creds.yaml

# Compile + prove in one step (finalize-time gate)
fractal-openshell-bridge verify ./my-pipeline/cells --credentials creds.yaml

Security posture

• Pure-function compiler. No temp files, no shared state, no side effects. Parallel invocations cannot cross-contaminate (nothing shared). Deterministic output (sorted keys, selective array sort) → identical input yields identical hash.
• Prover gate fail-closed when flagged. If --openshell-prover is set and the binary is absent or crashing, finalization blocks (exit 2). An attacker who deletes the binary or mutates $PATH cannot silently disable the gate. No-op only when the flag is entirely absent.
• No shell injection surface. Prover invoked via spawn with arg array, shell: false. Zero sidecar-derived data in any shell context.
• Input hardening. 1 MiB file-size cap + parse-depth limit before JSON.parse. Sidecar directory must never be agent-writable (TOCTOU defense).
• Policy file protection. policy.yaml is bind-mounted into the sandbox read-only (kernel-enforced), root-owned 0644, never in any FileChannel's allowedPaths, reinforced by Landlock, with the policy hash sealed into Fractal's Merkle root at finalize (tamper detection).
• Zero NVIDIA code. No OpenShell source bundled or forked. OpenShell consumed as an Apache-2.0 binary via subprocess. No upstream PR required.

What it is NOT

• Not a sandbox. It compiles a policy and invokes a prover. OpenShell does the enforcement.
• Not a substitute for human review. The compiler mapping and prover wiring are AI-authored and unreviewed. The generated policy.yaml is plain YAML — read it before applying it.
• Not a complete channel surface. Only the keeper channels are mapped. The dropped channels are documented, not silently ignored.

License

Apache-2.0. See LICENSE and NOTICE.