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.

feat(sidecar): binding digest + JS strip⇒fail preamble APIs

qybaihe92fab61ddf3c
diff --git a/src/index.ts b/src/index.ts
index fb0fc1b..5212cad 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -463,9 +463,19 @@ export {
export {
planSidecarEntanglement,
+ computeSidecarBindingDigest,
+ generateSidecarJsPreamble,
+ bindSidecarEntanglement,
+ entangleJsEntryWithSidecars,
SIDECAR_ENTANGLE_SCHEMA,
type SidecarEntanglePlan,
type SidecarEntanglePlanOptions,
+ type SidecarBindingPart,
+ type SidecarBindingDigest,
+ type SidecarBindingMode,
+ type SidecarJsInjectOptions,
+ type SidecarJsInjectResult,
+ type SidecarJsBindResult,
} from "./shields/runtime/sidecar-entangle.js";
export {
diff --git a/src/shields/runtime/sidecar-entangle.ts b/src/shields/runtime/sidecar-entangle.ts
index dfe795a..c78da01 100644
--- a/src/shields/runtime/sidecar-entangle.ts
+++ b/src/shields/runtime/sidecar-entangle.ts
@@ -2,10 +2,10 @@
* 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. Full binary
- * rewriting of non-JS sidecars remains out of scope (see
- * `docs/design/sidecar-entry-entanglement.md`); JS checker hosts receive
- * `generateSelfSealSnippet` payloads via protect/harden.
+ * 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.
*/
@@ -50,7 +50,7 @@ export interface SidecarEntanglePlan {
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";
+ readonly status: "ready" | "incomplete" | "bound";
readonly note: string;
readonly coverageMatrix: CoverageMatrix;
readonly coverageEvaluation: CoverageEvaluation;
@@ -166,3 +166,248 @@ export function planSidecarEntanglement(
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 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: `${inject.preamble}\n${entrySource}`,
+ };
+}
+
+/**
+ * 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)]),
+ ),
+ });
+}