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(self-seal): canonical entry self-digest hard-fails on entry tamper

qybaihe9f6e753f6c1b
diff --git a/src/engine/protector.ts b/src/engine/protector.ts
index 84173e2..bd67601 100644
--- a/src/engine/protector.ts
+++ b/src/engine/protector.ts
@@ -89,6 +89,7 @@ import {
jsWasmHydrateDumpRefuseMessage,
lintJsWasmHydrateDumpSource,
} from "./js-wasm-hydrate-dump-lint.js";
+import { finalizeSelfSealSelfDigest } from "../shields/runtime/self-seal.js";
/**
* Crash-safe output write: write to a temp file in the same directory, then
@@ -164,6 +165,11 @@ function writeFileAtomicSync(
): void {
const dir = dirname(targetPath);
mkdirSync(dir, { recursive: true });
+ // Self-seal entry self-digest must cover the FINAL bytes — finalize here, at
+ // the single write chokepoint, after every other transform.
+ const finalizeable =
+ typeof content !== "string" || encoding === undefined || encoding === "utf8";
+ if (finalizeable) content = finalizeSelfSealSelfDigest(content).content;
try {
const st = lstatSync(targetPath);
if (st.isSymbolicLink() || st.nlink > 1) {
diff --git a/src/shields/runtime/self-seal.ts b/src/shields/runtime/self-seal.ts
index f06d9e8..c091e3a 100644
--- a/src/shields/runtime/self-seal.ts
+++ b/src/shields/runtime/self-seal.ts
@@ -20,6 +20,15 @@
* hashes. Pair with `buildInterleavedCoverageMatrix` so packaging gates can refuse
* single-point topologies. Hash-only — no guessing.
*
+ * Entry self-coverage (CrackMe v8 red team 2026-11-05): in hard-fail mode each
+ * site also hard-fails when the checker host's **own** bytes diverge. A file
+ * cannot embed its own SHA-256, so the emitted literal starts as
+ * {@link SELF_DIGEST_PLACEHOLDER} and {@link finalizeSelfSealSelfDigest} (run on
+ * the final bytes at write time) replaces it with
+ * `SHA-256(file with every digest occurrence → "0"×64)`. Runtime recomputes the
+ * same canonical form. Until finalized the literal is not 64-hex and the self
+ * check soft-skips (never bricks an un-finalized build).
+ *
* DEFENSIVE ONLY. Opt-in. No crack / RE advice. Browser builds soft-skip (digest=0).
*/
@@ -32,6 +41,92 @@ import {
export const SELF_SEAL_SCHEMA = "bla-self-seal/v1" as const;
+/**
+ * Build-time placeholder for the entry self-digest literal (exactly 64 chars,
+ * deliberately non-hex so runtime soft-skips if a write path never finalized).
+ * Never ships: {@link finalizeSelfSealSelfDigest} replaces every occurrence.
+ */
+export const SELF_DIGEST_PLACEHOLDER =
+ "~self-digest-pending-finalize~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~" as const;
+
+const SELF_DIGEST_ZERO = "0".repeat(64);
+const HEX64_LOWER = /^[0-9a-f]{64}$/;
+
+function replaceAllBytes(buf: Buffer, needle: Buffer, replacement: Buffer): Buffer {
+ if (needle.length !== replacement.length) {
+ throw new Error("replaceAllBytes requires equal-length needle/replacement");
+ }
+ const out = Buffer.from(buf);
+ let at = out.indexOf(needle);
+ while (at !== -1) {
+ replacement.copy(out, at);
+ at = out.indexOf(needle, at + needle.length);
+ }
+ return out;
+}
+
+/** Canonical self-digest: SHA-256 of bytes with every `digestLiteral` → "0"×64. */
+export function canonicalSelfDigest(bytes: Buffer, digestLiteral: string): string {
+ const canon = replaceAllBytes(
+ bytes,
+ Buffer.from(digestLiteral, "latin1"),
+ Buffer.from(SELF_DIGEST_ZERO, "latin1"),
+ );
+ return createHash("sha256").update(canon).digest("hex");
+}
+
+export interface SelfDigestFinalizeResult<T extends string | Buffer> {
+ readonly content: T;
+ /** True when at least one placeholder was replaced. */
+ readonly applied: boolean;
+ readonly digest?: string;
+ readonly occurrences: number;
+}
+
+/**
+ * Replace {@link SELF_DIGEST_PLACEHOLDER} with the canonical self-digest of the
+ * **final** artifact bytes. Idempotent no-op when the placeholder is absent.
+ * Must run after every other transform (string encryption, source-map
+ * directives…) — any later byte change trips the runtime self check.
+ */
+export function finalizeSelfSealSelfDigest<T extends string | Buffer>(
+ content: T,
+): SelfDigestFinalizeResult<T> {
+ const asBuf: Buffer =
+ typeof content === "string" ? Buffer.from(content as string, "utf8") : (content as Buffer);
+ const needle = Buffer.from(SELF_DIGEST_PLACEHOLDER, "latin1");
+ let occurrences = 0;
+ for (let at = asBuf.indexOf(needle); at !== -1; at = asBuf.indexOf(needle, at + needle.length)) {
+ occurrences += 1;
+ }
+ if (occurrences === 0) return { content, applied: false, occurrences };
+ const zero = Buffer.from(SELF_DIGEST_ZERO, "latin1");
+ const canon = replaceAllBytes(asBuf, needle, zero);
+ const digest = createHash("sha256").update(canon).digest("hex");
+ const finalBuf = replaceAllBytes(asBuf, needle, Buffer.from(digest, "latin1"));
+ const out = (typeof content === "string" ? finalBuf.toString("utf8") : finalBuf) as T;
+ return { content: out, applied: true, digest, occurrences };
+}
+
+/**
+ * Offline check: does any 64-hex literal in `bytes` verify as the canonical
+ * self-digest? Used by harden to keep the coverage matrix honest (only claim
+ * entry self-coverage when the runtime check can actually hard-fail).
+ */
+export function verifySelfSealSelfDigest(bytes: Buffer): { readonly verified: boolean; readonly digest?: string } {
+ const text = bytes.toString("latin1");
+ const seen = new Set<string>();
+ const re = /["'`]([0-9a-f]{64})["'`]/g;
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(text)) !== null) {
+ const lit = m[1]!;
+ if (seen.has(lit)) continue;
+ seen.add(lit);
+ if (canonicalSelfDigest(bytes, lit) === lit) return { verified: true, digest: lit };
+ }
+ return { verified: false };
+}
+
export interface SelfSealOptions {
/** Extra sibling module paths to hash at runtime (relative or absolute). */
readonly siblingPaths?: readonly string[];
@@ -60,6 +155,12 @@ export interface SelfSealOptions {
readonly checkerHostPath?: string;
/** All protected file nodes (for coverage matrix); defaults to siblingPaths + host. */
readonly coverageFileNodes?: readonly string[];
+ /**
+ * Emit the canonical self-digest check on the checker host's own bytes.
+ * Default: true whenever siblings are present (hard-fail when
+ * hardFailOnSiblingMismatch, else poison digest).
+ */
+ readonly selfDigestCheck?: boolean;
}
export interface SelfSealSnippet {
@@ -77,6 +178,8 @@ export interface SelfSealSnippet {
readonly interleavedSites: number;
/** Coverage matrix for packaging gates / bla_lint_integrity_coverage. */
readonly coverageMatrix: CoverageMatrix;
+ /** True when sites embed {@link SELF_DIGEST_PLACEHOLDER} (finalize at write time). */
+ readonly selfDigestCheck: boolean;
}
function emitMeasureFunction(
@@ -85,6 +188,7 @@ function emitMeasureFunction(
expectedLiteral: string,
hardFailOnSiblingMismatch: boolean,
envFingerprint: boolean,
+ selfDigestCheck: boolean,
): string[] {
const lines: string[] = [];
lines.push(`function ${helperName}() {`);
@@ -100,9 +204,30 @@ function emitMeasureFunction(
lines.push(
` if (!selfPath && typeof __dirname === "string") selfPath = _path.join(__dirname, "index.js");`,
);
+ lines.push(` var selfBuf = null;`);
lines.push(
- ` if (selfPath) { try { h.update(_fs.readFileSync(selfPath)); } catch (_e) {} }`,
+ ` if (selfPath) { try { selfBuf = _fs.readFileSync(selfPath); h.update(selfBuf); } catch (_e) { selfBuf = null; } }`,
);
+ if (selfDigestCheck) {
+ // Canonical self-digest: zero every occurrence of the embedded literal, hash,
+ // compare. Literal is finalized at write time; non-hex → soft-skip.
+ lines.push(` var selfExpected = ${JSON.stringify(SELF_DIGEST_PLACEHOLDER)};`);
+ lines.push(` if (selfBuf && /^[0-9a-f]{64}$/.test(selfExpected)) {`);
+ lines.push(` var _lit = Buffer.from(selfExpected, "latin1");`);
+ lines.push(` var _zero = Buffer.alloc(64, 0x30);`);
+ lines.push(` var _canon = Buffer.from(selfBuf);`);
+ lines.push(` for (var _at = _canon.indexOf(_lit); _at !== -1; _at = _canon.indexOf(_lit, _at + 64)) _zero.copy(_canon, _at);`);
+ lines.push(
+ ` if (_c.createHash("sha256").update(_canon).digest("hex") !== selfExpected) {`,
+ );
+ if (hardFailOnSiblingMismatch) {
+ lines.push(` throw new Error("integrity check failed");`);
+ } else {
+ lines.push(` digest = 0xffffffff;`);
+ }
+ lines.push(` }`);
+ lines.push(` }`);
+ }
lines.push(` var siblings = ${siblingsLiteral};`);
lines.push(` var expected = ${expectedLiteral};`);
lines.push(` for (var i = 0; i < siblings.length; i++) {`);
@@ -191,6 +316,9 @@ export function generateSelfSealSnippet(
? 2
: 1;
+ const selfDigestCheck =
+ options.selfDigestCheck !== undefined ? options.selfDigestCheck : siblings.length > 0;
+
const siblingsLiteral = JSON.stringify(siblings);
const expectedLiteral = JSON.stringify(
Object.fromEntries(expectedEntries.map(([k, v]) => [k, v.toLowerCase()])),
@@ -212,6 +340,7 @@ export function generateSelfSealSnippet(
expectedLiteral,
hardFailOnSiblingMismatch,
envFingerprint,
+ selfDigestCheck,
),
);
}
@@ -256,6 +385,7 @@ export function generateSelfSealSnippet(
hardFailOnSiblingMismatch,
interleavedSites,
coverageMatrix,
+ selfDigestCheck,
};
}
diff --git a/tests/self-seal-self-digest.test.ts b/tests/self-seal-self-digest.test.ts
new file mode 100644
index 0000000..370e39f
--- /dev/null
+++ b/tests/self-seal-self-digest.test.ts
@@ -0,0 +1,113 @@
+/**
+ * Entry self-coverage (CrackMe v8 red team 2026-11-05).
+ *
+ * Red finding: the bla-integrity-coverage/v1 matrix claimed `license.cjs#siteN`
+ * hard-fail-verify `license.cjs`, but runtime only folded the entry's own bytes
+ * into the opaque digest — appending to the entry was indistinguishable from an
+ * intact run. These tests pin the canonical self-digest runtime fix.
+ */
+import { describe, expect, it } from "vitest";
+import { appendFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { SeededPrng } from "../src/core/prng.js";
+import {
+ SELF_DIGEST_PLACEHOLDER,
+ canonicalSelfDigest,
+ finalizeSelfSealSelfDigest,
+ generateSelfSealSnippet,
+ verifySelfSealSelfDigest,
+} from "../src/shields/runtime/self-seal.js";
+import { protectTarget } from "../src/engine/protector.js";
+
+function run(path: string) {
+ return spawnSync(process.execPath, [path], { encoding: "utf8" });
+}
+
+describe("self-seal canonical self-digest", () => {
+ it("placeholder is 64 chars and never valid hex (un-finalized → soft-skip)", () => {
+ expect(SELF_DIGEST_PLACEHOLDER).toHaveLength(64);
+ expect(/^[0-9a-f]{64}$/.test(SELF_DIGEST_PLACEHOLDER)).toBe(false);
+ });
+
+ it("finalize is a no-op without placeholder and verifies after replacement", () => {
+ const plain = "console.log(1);\n";
+ const noop = finalizeSelfSealSelfDigest(plain);
+ expect(noop.applied).toBe(false);
+ expect(noop.content).toBe(plain);
+
+ const src = `var a = "${SELF_DIGEST_PLACEHOLDER}"; var b = "${SELF_DIGEST_PLACEHOLDER}";\n`;
+ const fin = finalizeSelfSealSelfDigest(src);
+ expect(fin.applied).toBe(true);
+ expect(fin.occurrences).toBe(2);
+ expect(fin.content).not.toContain(SELF_DIGEST_PLACEHOLDER);
+ const bytes = Buffer.from(fin.content, "utf8");
+ expect(canonicalSelfDigest(bytes, fin.digest!)).toBe(fin.digest);
+ expect(verifySelfSealSelfDigest(bytes)).toEqual({ verified: true, digest: fin.digest });
+
+ // Any byte outside the digest literal breaks verification.
+ expect(verifySelfSealSelfDigest(Buffer.from(`${fin.content}//x`)).verified).toBe(false);
+ // Buffer input round-trips as Buffer.
+ const finBuf = finalizeSelfSealSelfDigest(Buffer.from(src, "utf8"));
+ expect(Buffer.isBuffer(finBuf.content)).toBe(true);
+ expect(finBuf.digest).toBe(fin.digest);
+ });
+
+ it("un-finalized snippet soft-skips the self check (never bricks a build)", () => {
+ const dir = mkdtempSync(join(tmpdir(), "bla-selfdig-soft-"));
+ try {
+ writeFileSync(join(dir, "asset.bin"), "a");
+ const snip = generateSelfSealSnippet(new SeededPrng("selfdig-soft"), {
+ siblingPaths: ["./asset.bin"],
+ bindingName: "integrityDigestSoft",
+ envFingerprint: false,
+ });
+ expect(snip.selfDigestCheck).toBe(true);
+ expect(snip.code).toContain(SELF_DIGEST_PLACEHOLDER);
+ const main = join(dir, "main.cjs");
+ writeFileSync(main, `"use strict";\n${snip.code}\nconsole.log("ok");\n`);
+ appendFileSync(main, "// edited\n");
+ const r = run(main);
+ expect(r.status, r.stderr).toBe(0);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("protect+self-seal hard-fails when the ENTRY itself is tampered", () => {
+ const dir = mkdtempSync(join(tmpdir(), "bla-selfdig-hf-"));
+ try {
+ writeFileSync(join(dir, "core.wasm"), Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0, 0, 0, 0xaa]));
+ const entry = join(dir, "gate.cjs");
+ writeFileSync(
+ entry,
+ ['"use strict";', "function main() { return 42; }", "module.exports = { main };",
+ "if (require.main === module) console.log(main());", ""].join("\n"),
+ );
+ const out = join(dir, "gate.out.cjs");
+ protectTarget({
+ inputPath: entry,
+ outputPath: out,
+ intensity: "balanced",
+ seed: "selfdig-protect",
+ selfSeal: true,
+ selfSealSiblingPaths: ["core.wasm"],
+ });
+ const shipped = readFileSync(out);
+ expect(shipped.includes(Buffer.from(SELF_DIGEST_PLACEHOLDER))).toBe(false);
+ expect(verifySelfSealSelfDigest(shipped).verified).toBe(true);
+
+ const intact = run(out);
+ expect(intact.status, intact.stderr).toBe(0);
+ expect(intact.stdout.trim()).toBe("42");
+
+ appendFileSync(out, "\n// patched\n");
+ const tampered = run(out);
+ expect(tampered.status).not.toBe(0);
+ expect(`${tampered.stderr}${tampered.stdout}`).toMatch(/integrity check failed/);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});