@fractalcode/bridge 0.1.0

package/dist/src/compiler/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * fractal-openshell-bridge — type definitions
+ *
+ * Input: Fractal `.channels.json` sidecar shape (plain JSON, no Fractal dependency).
+ * Output: OpenShell `PolicyFile` shape (mirrors the serde structs in
+ * openshell-policy/src/lib.rs).
+ */
+/** One typed channel declaration as written by Fractal at finalize time. */
+export interface TypedChannelConfig {
+    /** Cell's handle for the channel, e.g. "file", "llm", "tests". */
+    name: string;
+    /** Channel implementation kind, e.g. "file", "http", "anthropic". */
+    kind: string;
+    /** Frozen scope object; shape depends on `kind`. */
+    scope: Record<string, unknown>;
+}
+export interface FilesystemDef {
+    include_workdir: boolean;
+    read_only: string[];
+    read_write: string[];
+}
+export interface LandlockDef {
+    compatibility: string;
+}
+export interface ProcessDef {
+    run_as_user: string;
+    run_as_group: string;
+}
+export interface L7AllowDef {
+    method: string;
+    path?: string;
+}
+export interface L7RuleDef {
+    allow: L7AllowDef;
+}
+export interface NetworkEndpointDef {
+    host: string;
+    port?: number;
+    ports?: number[];
+    protocol: string;
+    tls?: string;
+    enforcement: string;
+    access?: string;
+    rules?: L7RuleDef[];
+}
+export interface NetworkBinaryDef {
+    path: string;
+}
+export interface NetworkPolicyRuleDef {
+    name: string;
+    endpoints: NetworkEndpointDef[];
+    binaries: NetworkBinaryDef[];
+}
+export interface PolicyFile {
+    version: 1;
+    filesystem_policy?: FilesystemDef;
+    landlock?: LandlockDef;
+    process?: ProcessDef;
+    network_policies: Record<string, NetworkPolicyRuleDef>;
+}
+export interface AuditLog {
+    /** Epoch milliseconds — supplied by the caller, NOT an input to policyHash. */
+    timestamp: number;
+    channelsProcessed: number;
+    skippedChannels: string[];
+    /** Human-readable notes about mapping limitations (e.g. protectedPaths carve-outs). */
+    anomaliesDetected: string[];
+}
+export interface CompilationResultOk {
+    success: true;
+    policyYaml: string;
+    /** SHA-256 of policyYaml only. Deterministic across runs for identical input. */
+    policyHash: string;
+    auditLog: AuditLog;
+}
+export interface CompilationResultErr {
+    success: false;
+    /** Stable machine-readable code, e.g. "input-too-large", "parse-depth-exceeded". */
+    code: string;
+    /** Human-readable error message. No stack trace (caller logs that separately). */
+    error: string;
+}
+export type CompilationResult = CompilationResultOk | CompilationResultErr;

package/dist/src/compiler/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * fractal-openshell-bridge — type definitions
+ *
+ * Input: Fractal `.channels.json` sidecar shape (plain JSON, no Fractal dependency).
+ * Output: OpenShell `PolicyFile` shape (mirrors the serde structs in
+ * openshell-policy/src/lib.rs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/prover/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * fractal-openshell-bridge — openshell-prover subprocess wrapper.
+ *
+ * Invokes the prover with `shell: false` and an arg array — zero sidecar-derived
+ * data reaches a shell context (red-team #4). Exit-code handling is explicit
+ * (red-team #1, corrected):
+ *   - flag NOT set         → not-enabled (no-op)
+ *   - binary absent        → fail-closed (the operator declared the constraint;
+ *                            an attacker who deletes the binary or mutates $PATH
+ *                            must not silently disable the gate)
+ *   - exit 0               → pass
+ *   - exit 1               → fail (critical/high findings)
+ *   - exit 2               → input error (bad YAML / missing files)
+ *   - any other non-zero   → crash → fail-closed (a crashing prover is not passing)
+ *
+ * The spawn function is injectable so tests can exercise every exit path without
+ * requiring openshell-prover to be installed.
+ */
+export interface ProverArgs {
+    policyPath: string;
+    credentialsPath: string;
+    registryPath?: string;
+    acceptedRisksPath?: string;
+    compact?: boolean;
+}
+export type ProverOutcome = "not-enabled" | "pass" | "fail" | "input-error" | "binary-absent-fail-closed" | "crash";
+export interface ProverResult {
+    outcome: ProverOutcome;
+    /** Raw exit code from the prover, or null if it didn't exit normally. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** Parsed finding lines (compact mode), when present. */
+    findings: string[];
+    /** Human-readable detail for non-pass outcomes. */
+    error?: string;
+}
+/** Default invocation: `openshell prove --policy ...`. Override for a standalone binary. */
+export declare const DEFAULT_PROVER_COMMAND: string[];
+export interface SpawnOutput {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    spawnError?: NodeJS.ErrnoException;
+}
+/** Injectable spawn implementation. */
+export type SpawnFn = (command: string[], args: string[]) => Promise<SpawnOutput>;
+/** Production spawn using child_process.spawn with shell:false. */
+export declare const defaultSpawn: SpawnFn;
+/**
+ * Run the openshell-prover against a compiled policy + credentials.
+ *
+ * @param args       Policy/credentials paths + options.
+ * @param opts       flagEnabled (operator declared the constraint), injectable
+ *                   spawn fn and prover command for testing.
+ */
+export declare function runProver(args: ProverArgs, opts: {
+    flagEnabled: boolean;
+    spawnFn?: SpawnFn;
+    proverCommand?: string[];
+}): Promise<ProverResult>;
+/** True if the prover result blocks finalization. */
+export declare function blocksFinalization(r: ProverResult): boolean;

package/dist/src/prover/index.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * fractal-openshell-bridge — openshell-prover subprocess wrapper.
+ *
+ * Invokes the prover with `shell: false` and an arg array — zero sidecar-derived
+ * data reaches a shell context (red-team #4). Exit-code handling is explicit
+ * (red-team #1, corrected):
+ *   - flag NOT set         → not-enabled (no-op)
+ *   - binary absent        → fail-closed (the operator declared the constraint;
+ *                            an attacker who deletes the binary or mutates $PATH
+ *                            must not silently disable the gate)
+ *   - exit 0               → pass
+ *   - exit 1               → fail (critical/high findings)
+ *   - exit 2               → input error (bad YAML / missing files)
+ *   - any other non-zero   → crash → fail-closed (a crashing prover is not passing)
+ *
+ * The spawn function is injectable so tests can exercise every exit path without
+ * requiring openshell-prover to be installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSpawn = exports.DEFAULT_PROVER_COMMAND = void 0;
+exports.runProver = runProver;
+exports.blocksFinalization = blocksFinalization;
+const child_process_1 = require("child_process");
+/** Default invocation: `openshell prove --policy ...`. Override for a standalone binary. */
+exports.DEFAULT_PROVER_COMMAND = ["openshell", "prove"];
+/** Production spawn using child_process.spawn with shell:false. */
+const defaultSpawn = (command, args) => new Promise((resolve) => {
+    const child = (0, child_process_1.spawn)(command[0], [...command.slice(1), ...args], {
+        shell: false,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (d) => {
+        stdout += d.toString();
+    });
+    child.stderr?.on("data", (d) => {
+        stderr += d.toString();
+    });
+    child.on("error", (err) => {
+        resolve({ code: null, stdout, stderr, spawnError: err });
+    });
+    child.on("close", (code) => {
+        resolve({ code: code ?? null, stdout, stderr });
+    });
+});
+exports.defaultSpawn = defaultSpawn;
+/** Validate that a path looks like a real path (no shell metacharacters). */
+function validatePath(p, label) {
+    if (typeof p !== "string" || p.length === 0)
+        return `${label} is required`;
+    // Reject shell metacharacters defensively — even though shell:false, this
+    // prevents a malformed path from being passed as an argv element that could
+    // confuse the prover's own arg parsing.
+    if (/[;<>&|`$()]/.test(p))
+        return `${label} contains forbidden characters`;
+    return null;
+}
+/**
+ * Run the openshell-prover against a compiled policy + credentials.
+ *
+ * @param args       Policy/credentials paths + options.
+ * @param opts       flagEnabled (operator declared the constraint), injectable
+ *                   spawn fn and prover command for testing.
+ */
+async function runProver(args, opts) {
+    if (!opts.flagEnabled) {
+        return {
+            outcome: "not-enabled",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            findings: [],
+        };
+    }
+    for (const [label, p] of [
+        ["policyPath", args.policyPath],
+        ["credentialsPath", args.credentialsPath],
+    ]) {
+        const err = validatePath(p, label);
+        if (err) {
+            return {
+                outcome: "input-error",
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                findings: [],
+                error: err,
+            };
+        }
+    }
+    const argv = ["--policy", args.policyPath, "--credentials", args.credentialsPath];
+    if (args.registryPath)
+        argv.push("--registry", args.registryPath);
+    if (args.acceptedRisksPath)
+        argv.push("--accepted-risks", args.acceptedRisksPath);
+    if (args.compact)
+        argv.push("--compact");
+    const command = opts.proverCommand ?? exports.DEFAULT_PROVER_COMMAND;
+    const spawnFn = opts.spawnFn ?? exports.defaultSpawn;
+    let out;
+    try {
+        out = await spawnFn(command, argv);
+    }
+    catch (err) {
+        return {
+            outcome: "crash",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            findings: [],
+            error: `prover invocation threw: ${err.message}`,
+        };
+    }
+    // Binary absent (ENOENT) → fail-closed because flag is set.
+    if (out.spawnError && out.spawnError.code === "ENOENT") {
+        return {
+            outcome: "binary-absent-fail-closed",
+            exitCode: null,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            findings: [],
+            error: `openshell-prover binary not found (ENOENT). The gate flag was set, so finalization is blocked — install openshell-prover or unset the flag. stderr: ${out.stderr}`,
+        };
+    }
+    // Any other spawn error → fail-closed (crash).
+    if (out.spawnError) {
+        return {
+            outcome: "crash",
+            exitCode: null,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            findings: [],
+            error: `prover failed to spawn: ${out.spawnError.message}`,
+        };
+    }
+    const code = out.code;
+    const findings = parseFindings(out.stdout);
+    if (code === 0) {
+        return { outcome: "pass", exitCode: code, stdout: out.stdout, stderr: out.stderr, findings };
+    }
+    if (code === 1) {
+        return {
+            outcome: "fail",
+            exitCode: code,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            findings,
+            error: `prover reported critical/high findings (${findings.length} finding path(s))`,
+        };
+    }
+    if (code === 2) {
+        return {
+            outcome: "input-error",
+            exitCode: code,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            findings,
+            error: `prover input error: ${out.stderr.trim() || out.stdout.trim()}`,
+        };
+    }
+    // Any other non-zero (or null) → crash → fail-closed.
+    return {
+        outcome: "crash",
+        exitCode: code,
+        stdout: out.stdout,
+        stderr: out.stderr,
+        findings,
+        error: `prover exited with unexpected code ${code} (crash). A crashing prover is not a passing prover. stderr: ${out.stderr.trim()}`,
+    };
+}
+/** Parse compact-mode finding lines from prover stdout. */
+function parseFindings(stdout) {
+    return stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && /•|REVIEW|link_local|l7_bypass|credential_reach|capability_expansion/.test(l));
+}
+/** True if the prover result blocks finalization. */
+function blocksFinalization(r) {
+    return (r.outcome === "fail" ||
+        r.outcome === "input-error" ||
+        r.outcome === "binary-absent-fail-closed" ||
+        r.outcome === "crash");
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fractalcode/bridge",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "fractal-openshell-bridge": "dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "demo": "node examples/dual-gate/demo.js",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-security",
+    "sandbox",
+    "openshell",
+    "fractal-code",
+    "policy",
+    "defense-in-depth"
+  ],
+  "author": "Angelo Regalbuto / Regal Health & Retirement LLC",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^3.0.0"
+  }
+}