🛡️ 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.
JavaScript adversarial-aiclaude-codecursorelectron-securityllm-securitymcpmcp-serverobfuscationreverse-engineeringwebassembly
docs(design): sidecar/entry entanglement DESIGN + planner stub
qybaihe6540160490f9
diff --git a/docs/design/sidecar-entry-entanglement.md b/docs/design/sidecar-entry-entanglement.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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");+ });+});