🛡️ 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
/**
* Sidecar / entry entanglement planner (issue #40 / Direction-3).
*
* Elevates the former planned-stub into a coverage-matrix planner that assigns
* interleaved SHA-256 check edges across entry + sidecar paths. JS strip⇒fail rewrite is available via `bindSidecarEntanglement` /
* `generateSidecarJsPreamble` when `sidecarEntangle` is set (see
* `docs/design/sidecar-entry-entanglement.md`). Non-JS / Python preamble
* rewrite remains a follow-up; WASM custom-section notes TBD.
*
* DEFENSIVE ONLY. Hash-only — no guessing.
*/
import { existsSync, readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { join, isAbsolute } from "node:path";
import {
INTEGRITY_COVERAGE_SCHEMA,
buildInterleavedCoverageMatrix,
evaluateCoverageMatrix,
finalizeCoverageMatrixHashes,
type CoverageEvaluation,
type CoverageMatrix,
} from "../../engine/integrity-coverage.js";
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;
/**
* Optional on-disk bytes (or absolute paths to read) keyed by the same relative
* paths listed in entry/sidecars — used to finalize expectedSha256.
*/
readonly fileBytes?: Readonly<Record<string, Buffer | string>>;
/** Absolute directory used to resolve relative paths when reading hashes. */
readonly baseDir?: string;
}
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";
/** `ready` when coverage matrix satisfies refuse predicates; else `incomplete`. */
readonly status: "ready" | "incomplete" | "bound";
readonly note: string;
readonly coverageMatrix: CoverageMatrix;
readonly coverageEvaluation: CoverageEvaluation;
}
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";
}
function isJsChecker(path: string): boolean {
return /\.(mjs|cjs|js|ts|tsx|jsx)$/i.test(path);
}
/**
* Plan interleaved sidecar↔entry entanglement as a coverage matrix.
* Reads optional on-disk bytes to finalize hashes when `baseDir` + paths exist.
*/
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);
const fileNodes = [...new Set([options.entryPath, ...sidecars])].sort();
const checkerHosts = fileNodes.filter(isJsChecker);
// Prefer entry as a checker host even if list empty.
const hosts =
checkerHosts.length > 0
? checkerHosts
: isJsChecker(options.entryPath)
? [options.entryPath]
: [];
let expected: Record<string, string> = {};
const supplied = options.fileBytes ?? {};
for (const [k, v] of Object.entries(supplied)) {
expected[k] = createHash("sha256")
.update(typeof v === "string" ? Buffer.from(v) : v)
.digest("hex");
}
// Optionally read from disk when baseDir is provided.
if (options.baseDir) {
for (const rel of fileNodes) {
if (expected[rel]) continue;
const abs = isAbsolute(rel) ? rel : join(options.baseDir, rel);
try {
if (existsSync(abs)) {
expected[rel] = createHash("sha256")
.update(readFileSync(abs))
.digest("hex");
}
} catch {
/* leave missing — evaluate will refuse */
}
}
}
let matrix = buildInterleavedCoverageMatrix({
fileNodes,
checkerHosts: hosts.length > 0 ? hosts : [options.entryPath],
expectedSha256: expected,
colocatedSites: 2,
});
matrix = finalizeCoverageMatrixHashes(matrix, {
...Object.fromEntries(
Object.entries(supplied).map(([k, v]) => [
k,
typeof v === "string" ? Buffer.from(v) : v,
]),
),
});
// Re-apply disk hashes into finalize if we computed expected above.
if (Object.keys(expected).length > 0) {
matrix = {
schema: INTEGRITY_COVERAGE_SCHEMA,
nodes: matrix.nodes,
edges: matrix.edges,
expectedSha256: { ...matrix.expectedSha256, ...expected },
};
matrix = finalizeCoverageMatrixHashes(matrix, {});
}
const coverageEvaluation = evaluateCoverageMatrix(matrix);
const status = coverageEvaluation.ok ? "ready" : "incomplete";
return {
schema: SIDECAR_ENTANGLE_SCHEMA,
entryPath: options.entryPath,
sidecarPaths: sidecars,
digestAlgorithm: "sha256",
seedTag,
softFold: options.softFold === true,
planId,
entryHookKind: guessHookKind(options.entryPath),
status,
note: coverageEvaluation.ok
? "Interleaved coverage matrix ready — wire checkers via self-seal / protect."
: `Coverage incomplete: ${coverageEvaluation.reasons.join(", ")}. ${coverageEvaluation.oneLineAdvice}`,
coverageMatrix: matrix,
coverageEvaluation,
};
}
/** A labelled entry- or sidecar-file measurement for offline binding. */
export interface SidecarBindingPart {
readonly pathLabel: string;
readonly bytes: Uint8Array;
}
export interface SidecarBindingDigest {
/** Full SHA-256 hex over entry‖sidecars‖seedTag (mode-dependent). */
readonly hex: string;
/** First 8 hex chars folded to an unsigned 32-bit int (matches self-seal fold shape). */
readonly u32: number;
}
/**
* Binding modes:
* - "sidecars" (default): hash entry path label + each sidecar path‖bytes + seedTag.
* Safe to prepend a preamble to the entry without invalidating the digest
* (strip⇒fail targets sidecar removal/tamper; entry body integrity is self-seal).
* - "full": also fold entry.bytes (protect-time snapshot). Use only when the
* entry will not be rewritten after the digest is sealed.
*/
export type SidecarBindingMode = "sidecars" | "full";
/**
* Compute the offline binding digest for an entry and its sidecars.
*
* DEFENSIVE ONLY — integrity binding, not an encryption primitive.
*/
export function computeSidecarBindingDigest(
entry: SidecarBindingPart,
sidecars: readonly SidecarBindingPart[],
seedTag = "bla-sidecar-v1",
mode: SidecarBindingMode = "sidecars",
): SidecarBindingDigest {
const h = createHash("sha256");
h.update(entry.pathLabel);
h.update("\0");
if (mode === "full") {
h.update(entry.bytes);
h.update("\0");
}
for (const s of sidecars) {
h.update(s.pathLabel);
h.update("\0");
h.update(s.bytes);
h.update("\0");
}
h.update(seedTag);
const hex = h.digest("hex");
return { hex, u32: parseInt(hex.slice(0, 8), 16) >>> 0 };
}
export interface SidecarJsInjectOptions {
readonly entryPath: string;
readonly sidecarPaths: readonly string[];
readonly seedTag?: string;
/** Offline expected digest (from computeSidecarBindingDigest). Required for hard fail. */
readonly expectedHex: string;
/** Binding name for the measured digest (tests / soft-fold). */
readonly bindingName?: string;
/**
* When true, emit a soft fold that only flips the measured u32 on mismatch
* (caller entangles with opaque seed). When false (default), throw on mismatch.
*/
readonly softFold?: boolean;
}
export interface SidecarJsInjectResult {
readonly schema: typeof SIDECAR_ENTANGLE_SCHEMA;
readonly preamble: string;
readonly bindingName: string;
readonly expectedHex: string;
readonly expectedU32: number;
readonly softFold: boolean;
readonly sidecarCount: number;
}
/**
* Emit a Node JS preamble that re-measures sidecar siblings and compares
* against the protect-time SHA-256 hex. Strip / alter ⇒ throw (hard) or
* expose a flipped digest (softFold) for opaque-seed entanglement.
*
* DEFENSIVE ONLY. Opt-in. No crack / RE advice.
*/
export function generateSidecarJsPreamble(
options: SidecarJsInjectOptions,
): SidecarJsInjectResult {
const sidecars = (options.sidecarPaths ?? []).filter((p) => p.length > 0);
const seedTag = options.seedTag ?? "bla-sidecar-v1";
const softFold = options.softFold === true;
const bindingName = options.bindingName ?? "__blaSidecarDigest";
const expectedHex = options.expectedHex.toLowerCase();
if (!/^[0-9a-f]{64}$/.test(expectedHex)) {
throw new Error("expectedHex must be a 64-char lowercase hex SHA-256 digest");
}
const expectedU32 = parseInt(expectedHex.slice(0, 8), 16) >>> 0;
const sidecarsLiteral = JSON.stringify(sidecars);
const entryLiteral = JSON.stringify(options.entryPath);
const seedLiteral = JSON.stringify(seedTag);
const lines: string[] = [];
lines.push(`(function(){`);
lines.push(` var __expected = ${JSON.stringify(expectedHex)};`);
lines.push(` var ${bindingName} = 0;`);
lines.push(` try {`);
lines.push(` var _c = require("node:crypto");`);
lines.push(` var _fs = require("node:fs");`);
lines.push(` var _path = require("node:path");`);
lines.push(` var h = _c.createHash("sha256");`);
lines.push(` var entryLabel = ${entryLiteral};`);
lines.push(` h.update(entryLabel);`);
lines.push(` h.update(String.fromCharCode(0));`);
lines.push(` var sidecars = ${sidecarsLiteral};`);
lines.push(` for (var i = 0; i < sidecars.length; i++) {`);
lines.push(` var sp = sidecars[i];`);
lines.push(` var spAbs = sp;`);
lines.push(
` if (!_path.isAbsolute(spAbs) && typeof __dirname === "string") spAbs = _path.join(__dirname, sp);`,
);
lines.push(` h.update(sp);`);
lines.push(` h.update(String.fromCharCode(0));`);
lines.push(
` try { h.update(_fs.readFileSync(spAbs)); } catch (_e1) { h.update("missing:" + String(sp)); }`,
);
lines.push(` h.update(String.fromCharCode(0));`);
lines.push(` }`);
lines.push(` h.update(${seedLiteral});`);
lines.push(` var hex = h.digest("hex");`);
lines.push(` ${bindingName} = parseInt(hex.slice(0, 8), 16) >>> 0;`);
if (softFold) {
lines.push(
` if (hex !== __expected) { ${bindingName} = (${bindingName} ^ 0xffffffff) >>> 0; }`,
);
} else {
lines.push(
` if (hex !== __expected) { throw new Error("integrity binding mismatch"); }`,
);
}
lines.push(` } catch (_e2) {`);
if (softFold) {
lines.push(` ${bindingName} = 0;`);
} else {
lines.push(
` if (_e2 && _e2.message === "integrity binding mismatch") throw _e2;`,
);
lines.push(` throw new Error("integrity binding mismatch");`);
}
lines.push(` }`);
lines.push(` return ${bindingName};`);
lines.push(`})();`);
return {
schema: SIDECAR_ENTANGLE_SCHEMA,
preamble: lines.join("\n"),
bindingName,
expectedHex,
expectedU32,
softFold,
sidecarCount: sidecars.length,
};
}
export interface SidecarJsBindResult {
readonly plan: SidecarEntanglePlan;
readonly digest: SidecarBindingDigest;
readonly inject: SidecarJsInjectResult;
/** Entry source with the strip⇒fail preamble prepended. */
readonly code: string;
}
/**
* Plan + bind for a JS entry: compute the offline digest from in-memory
* sidecar bytes and return a `bound` plan plus the rewritten entry source.
*
* Uses sidecars-mode digest so the prepended preamble does not invalidate H.
*/
export function bindSidecarEntanglement(
options: SidecarEntanglePlanOptions & {
readonly entryBytes: Uint8Array;
readonly sidecarBytes: readonly Uint8Array[];
/** Original entry source to prepend into. Defaults to utf8 of entryBytes. */
readonly entrySource?: string;
},
): SidecarJsBindResult {
const plan = planSidecarEntanglement(options);
if (options.sidecarBytes.length !== plan.sidecarPaths.length) {
throw new Error("sidecarBytes length must match sidecarPaths length");
}
const digest = computeSidecarBindingDigest(
{ pathLabel: options.entryPath, bytes: options.entryBytes },
plan.sidecarPaths.map((pathLabel, i) => ({
pathLabel,
bytes: options.sidecarBytes[i]!,
})),
plan.seedTag,
"sidecars",
);
const inject = generateSidecarJsPreamble({
entryPath: options.entryPath,
sidecarPaths: plan.sidecarPaths,
seedTag: plan.seedTag,
expectedHex: digest.hex,
softFold: plan.softFold,
});
const entrySource =
options.entrySource ?? new TextDecoder().decode(options.entryBytes);
const shebangMatch = entrySource.match(/^#![^\n]*\r?\n/);
const shebang = shebangMatch ? shebangMatch[0] : "";
const afterShebang = shebang ? entrySource.slice(shebang.length) : entrySource;
const strictMatch = afterShebang.match(/^["']use strict["'];?\r?\n/);
const strict = strictMatch ? strictMatch[0] : "";
const body = strict ? afterShebang.slice(strict.length) : afterShebang;
const boundPlan: SidecarEntanglePlan = {
...plan,
status: "bound",
note: "Bound — JS preamble ready; prepend to entry and ship sidecars alongside. Strip/alter fails closed.",
};
return {
plan: boundPlan,
digest,
inject,
code: `${shebang}${strict}${inject.preamble}\n${body}`,
};
}
/**
* Convenience: given final on-disk sidecar bytes + entry source, produce the
* strip⇒fail-bound entry. Returns null when there are no sidecars to bind.
*/
export function entangleJsEntryWithSidecars(options: {
readonly entryPath: string;
readonly entrySource: string;
readonly sidecars: readonly SidecarBindingPart[];
readonly seedTag?: string;
readonly softFold?: boolean;
}): SidecarJsBindResult | null {
if (options.sidecars.length === 0) return null;
return bindSidecarEntanglement({
entryPath: options.entryPath,
sidecarPaths: options.sidecars.map((s) => s.pathLabel),
seedTag: options.seedTag,
softFold: options.softFold,
entryBytes: new TextEncoder().encode(options.entrySource),
sidecarBytes: options.sidecars.map((s) => s.bytes),
entrySource: options.entrySource,
fileBytes: Object.fromEntries(
options.sidecars.map((s) => [s.pathLabel, Buffer.from(s.bytes)]),
),
});
}