Skip to content

armgit / bla

Public Imported from GitHub
0

🛡️ BLA (Blind LLM Agents) — Adversarial defense shield that protects binaries, Electron apps, JS bundles, Python, and WebAssembly against AI reverse-engineering agents like REA. Poison -> Exhaust -> Hallucinate.

docs(design): sidecar/entry entanglement DESIGN + planner stub

qybaihe6540160490f9
diff --git a/docs/design/sidecar-entry-entanglement.md b/docs/design/sidecar-entry-entanglement.md
new file mode 100644
index 0000000..2720807
--- /dev/null
+++ b/docs/design/sidecar-entry-entanglement.md
@@ -0,0 +1,42 @@
+# DESIGN: Sidecar / entry entanglement (issue #40 / STATE)
+
+Status: **first-slice stub** — design locked; full multi-format entanglement TBD.
+
+## Goal
+
+Decoy / chaff sidecars must not be dismissible as an "independent protection layer".
+If an attacker strips a sidecar or decoy file, the **entry** (main module / primary
+artifact) must fail closed (integrity mismatch), not keep running happily.
+
+This is the same honesty principle as weave-decoy: shared state + entry-reachable
+checks beat orphan honeypot files.
+
+## Non-goals
+
+- No crack / RE playbooks.
+- No claim that entanglement equals cryptographic unbreakability.
+- No mandatory sidecar for every format in 1.6.x.
+
+## Design (v1)
+
+1. **Binding digest** — at protect time, compute `H = SHA-256(entryBytes || sidecarBytes || seedTag)`.
+2. **Entry hook** — inject a tiny preamble (JS/Python) or custom-section note (WASM) that
+ re-measures sibling sidecar path(s) and compares to `H` (or folds `H` into the opaque seed /
+ self-seal digest — see `#40.5`).
+3. **Strip ⇒ fail** — missing or altered sidecar changes the digest → opaque happy-path /
+ activation gate fails.
+4. **Opt-in** — `sidecarEntangle: true` in `.blarc` / CLI / MCP (not enabled by default until
+ format coverage is broader).
+
+## First slice (this batch)
+
+- This DESIGN note (normative intent).
+- Stub helper `planSidecarEntanglement()` returning a `bla-sidecar-entangle/v1` plan
+ object (paths, digest algorithm, entry hook kind) **without** rewriting binaries yet.
+- Unit tests for the planner.
+
+## Follow-ups
+
+- Wire planner into `protectTarget` for JS + Python when `sidecarEntangle` is set.
+- Extend to ASAR / Bun snapshot / native companion files.
+- Honesty: when entanglement is off, defenseScore gap annotation (like self-seal).
diff --git a/src/shields/runtime/sidecar-entangle.ts b/src/shields/runtime/sidecar-entangle.ts
new file mode 100644
index 0000000..c292090
--- /dev/null
+++ b/src/shields/runtime/sidecar-entangle.ts
@@ -0,0 +1,75 @@
+/**
+ * Sidecar / entry entanglement planner stub (issue #40 / STATE).
+ *
+ * Full binary rewriting is intentionally deferred — see
+ * `docs/design/sidecar-entry-entanglement.md`. This module returns a typed plan
+ * agents can inspect before enabling the future opt-in flag.
+ *
+ * DEFENSIVE ONLY.
+ */
+
+import { createHash } from "node:crypto";
+
+export const SIDECAR_ENTANGLE_SCHEMA = "bla-sidecar-entangle/v1" as const;
+
+export interface SidecarEntanglePlanOptions {
+ readonly entryPath: string;
+ readonly sidecarPaths: readonly string[];
+ readonly seedTag?: string;
+ /** When true, plan folds the binding into self-seal / opaque seed rather than a hard throw. */
+ readonly softFold?: boolean;
+}
+
+export interface SidecarEntanglePlan {
+ readonly schema: typeof SIDECAR_ENTANGLE_SCHEMA;
+ readonly entryPath: string;
+ readonly sidecarPaths: readonly string[];
+ readonly digestAlgorithm: "sha256";
+ readonly seedTag: string;
+ readonly softFold: boolean;
+ /** Offline binding id (hash of paths + seedTag) — not the runtime content digest. */
+ readonly planId: string;
+ readonly entryHookKind: "js-preamble" | "python-preamble" | "wasm-custom-section" | "unspecified";
+ readonly status: "planned-stub";
+ readonly note: string;
+}
+
+function guessHookKind(entryPath: string): SidecarEntanglePlan["entryHookKind"] {
+ const lower = entryPath.toLowerCase();
+ if (/\.(mjs|cjs|js|ts|tsx|jsx)$/.test(lower)) return "js-preamble";
+ if (/\.py$/.test(lower)) return "python-preamble";
+ if (/\.wasm$/.test(lower)) return "wasm-custom-section";
+ return "unspecified";
+}
+
+/**
+ * Plan a sidecar↔entry entanglement binding. Does not read or rewrite files.
+ */
+export function planSidecarEntanglement(
+ options: SidecarEntanglePlanOptions,
+): SidecarEntanglePlan {
+ const sidecars = (options.sidecarPaths ?? []).filter((p) => p.length > 0);
+ const seedTag = options.seedTag ?? "bla-sidecar-v1";
+ const planId = createHash("sha256")
+ .update(options.entryPath)
+ .update("\0")
+ .update(sidecars.join("\0"))
+ .update("\0")
+ .update(seedTag)
+ .digest("hex")
+ .slice(0, 16);
+
+ return {
+ schema: SIDECAR_ENTANGLE_SCHEMA,
+ entryPath: options.entryPath,
+ sidecarPaths: sidecars,
+ digestAlgorithm: "sha256",
+ seedTag,
+ softFold: options.softFold === true,
+ planId,
+ entryHookKind: guessHookKind(options.entryPath),
+ status: "planned-stub",
+ note:
+ "Stub planner only — enable full rewrite when sidecarEntangle lands in protect paths. See docs/design/sidecar-entry-entanglement.md.",
+ };
+}
diff --git a/tests/sidecar-entangle-plan.test.ts b/tests/sidecar-entangle-plan.test.ts
new file mode 100644
index 0000000..d35d4c7
--- /dev/null
+++ b/tests/sidecar-entangle-plan.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import {
+ planSidecarEntanglement,
+ SIDECAR_ENTANGLE_SCHEMA,
+} from "../src/shields/runtime/sidecar-entangle.js";
+
+describe("sidecar entry entanglement planner stub", () => {
+ it("returns a bla-sidecar-entangle/v1 plan with stable planId", () => {
+ const a = planSidecarEntanglement({
+ entryPath: "dist/main.js",
+ sidecarPaths: ["dist/main.js.bla-sidecar", "dist/assets.chaff"],
+ seedTag: "test-seed",
+ });
+ const b = planSidecarEntanglement({
+ entryPath: "dist/main.js",
+ sidecarPaths: ["dist/main.js.bla-sidecar", "dist/assets.chaff"],
+ seedTag: "test-seed",
+ });
+ expect(a.schema).toBe(SIDECAR_ENTANGLE_SCHEMA);
+ expect(a.status).toBe("planned-stub");
+ expect(a.entryHookKind).toBe("js-preamble");
+ expect(a.planId).toBe(b.planId);
+ expect(a.digestAlgorithm).toBe("sha256");
+ expect(a.sidecarPaths).toHaveLength(2);
+ });
+
+ it("guesses python / wasm hook kinds", () => {
+ expect(
+ planSidecarEntanglement({ entryPath: "app.py", sidecarPaths: ["app.pyc"] })
+ .entryHookKind,
+ ).toBe("python-preamble");
+ expect(
+ planSidecarEntanglement({ entryPath: "core.wasm", sidecarPaths: ["core.name"] })
+ .entryHookKind,
+ ).toBe("wasm-custom-section");
+ });
+});