Merge pull request #230 from qybaihe/fix/esm-import-hoist-honesty

feat(honesty): annotate ESM import-hoist before sidecar/self-seal hooks
This commit is contained in:
Timo Zhang
2026-11-16 23:50:56 +08:00
committed by GitHub
11 changed files with 305 additions and 7 deletions
+2 -1
View File
@@ -123,7 +123,8 @@ Also: do **not** ship a stable public WASM ABI without explicit `wasm_preserve_e
- Optional bind-scope (domain/date) is a **public** license contract (`bla_bind_scope` → `bind-scope.json` + `BLA_BIND_SCOPE_CHECK`). Default OFF. Never a covert backdoor — `public:true` mandatory; lint with `bla_lint_bind_scope`.
- Coverage claims must be real, not paper: an entry may only count as covering itself when its runtime check hard-fails on its own bytes (canonical self-digest, finalized at write). Check `integrityCoverageSelfVerified` on the harden report; when false the matrix drops self edges and refuses. Keep host-trust values (e.g. certificate digests) inside a covered artifact — unhardened data sidecars like `seal.json` are not covered.
- A countered strip⇒fail sidecar vector (`asar-sidecar-entangle`, or `pyc-sidecar-entangle` / `gguf-sidecar-entangle` once they exist at import/load time) may be recorded only when the entry hook hard-fails at process start, import, or load. A host-only verifier (for example `verifyPycSidecarMarshalNote` on a `.pyc` TYPE_ASCII trailer that `importlib` ignores, or `verifyGgufSidecarMetadataNote` on a GGUF `bla.sidecar.v1` STRING KV that loaders ignore) is a binding note, not coverage: do not list the vector, and do not treat enabling it as closing the `sidecar-entangle-not-enabled` defenseScore gap (annotate `pyc-sidecar-host-verify-only` / `gguf-sidecar-host-verify-only` instead).
- **Runtime carrier decides whether a preamble is safe, not file syntax alone:** a CommonJS strip⇒fail preamble (`require`, `__dirname`) on an entry that the runtime evaluates as an ES module breaks the *intact* artifact — that is a functional-equivalence failure, not protection. Treat `.mjs`, static import/export, top-level `await`, `import.meta`, and a `.js` / `.ts` under the nearest `package.json` `"type": "module"` as module scope; refuse (and say so) rather than ship (red 2026-11-13).
- **Runtime carrier decides whether a preamble is safe, not file syntax alone:** a CommonJS strip⇒fail preamble (`require`, `__dirname`) on an entry that the runtime evaluates as an ES module breaks the *intact* artifact — that is a functional-equivalence failure, not protection. Treat `.mjs`, static import/export, top-level `await`, `import.meta`, and a `.js` / `.ts` under the nearest `package.json` `"type": "module"` as module scope and ship the ESM-native preamble (`import { createRequire } from "node:module"` + `import.meta.url`), not a CommonJS one (red 2026-11-13 / #200).
- **ESM static imports are hoisted before the entry hook:** a prepended sidecarEntangle / self-seal IIFE fail-closes the *entry body*, but the ESM loader instantiates static `import` / `export-from` bindings first, so imported module side effects still run after a sidecar strip or hook failure. That is not process-start strip⇒fail for the hoisted graph (CJS `require()` after the preamble is). Annotate defenseScore gap `esm-import-hoist-before-hooks` (soft-cap 93) and do not overclaim "full runtime" coverage (red 2026-11-16).
- **Pinned sibling digests must fail-closed on absence:** if an entry pins `EXPECTED_*_SHA256` (or equivalent) for a data sidecar, `ENOENT` / unreadable MUST throw the same integrity-class error as digest mismatch. Never soft-fold missing pinned files into business `DENIED` — catch blocks that only rethrow `/integrity/` and map everything else to DENIED are a footgun (CrackMe v9 red 2026-11-10: `seal.json` delete looked like a wrong key).
Held across R8–R12 (NO PRIZE). Keep in gate design; do **not** invent packaging refuse lints for these:
+3
View File
@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- **defenseScore honesty gap `esm-import-hoist-before-hooks` (soft-cap 93):** ESM static `import` / `export-from` bindings are instantiated before any statement in the entry, including the prepended `sidecarEntangle` / `self-seal` IIFE. The entry body still fail-closes on sidecar strip or hook failure, but imported module side effects already ran — this is not process-start strip⇒fail for the hoisted graph (CJS `require()` after the preamble is unaffected). `jsModuleHasHoistedDependencyGraph` detects the case (ignoring the BLA `createRequire` preamble); `verifyTarget` annotates the gap when sidecar or self-seal is on. Skill B / DESIGN / MCP / CLI wording updated so "full runtime strip⇒fail" is not overclaimed (red 2026-11-16).
## [3.4.1] — 2026-11-15
Patch adding an optional **JS-loader hook** for WASM `bla.sidecar.v1` custom-section verification, plus `REA_INTERNAL_LIMITS` catalog hygiene for REA's new JavaScript member-mutation work allowance.
+1 -1
View File
@@ -110,7 +110,7 @@ CrackMe v9 Sovereign red team (round-20261110): **NO PRIZE** — key/FLAG not re
## Nightly roadmap remaining
1. ~~**Self-seal / defenseScore honesty (#40)**~~ — landed soft-caps + opt-in `--self-seal` / MCP `self_seal` / `.blarc selfSeal` (batch 2026-11-02). Remaining: deeper onefile/peel score model.
2. **Sidecar entry entanglement** — JS strip⇒fail landed 2026-11-05; Python preamble landed 2026-11-06 nightly; WASM `bla.sidecar.v1` custom-section + host verify landed 2026-11-07 nightly; Bun `.bla-sidecar.v1.json` companion + defenseScore `sidecar-entangle-not-enabled` gap landed 2026-11-08 nightly; ASAR `.bla/sidecar.v1.json` archive-note landed 2026-11-09 nightly; ASAR main JS preamble landed 2026-11-10 nightly; `.pyc` TYPE_ASCII marshal trailer (host verify) landed 2026-11-11 nightly — **2026-11-12 honesty:** do not record `pyc-sidecar-entangle` / do not clear the strip⇒fail defenseScore gap until an import-time hook lands (`pyc-sidecar-host-verify-only`); GGUF STRING metadata note landed 2026-11-12 (`gguf-sidecar-host-verify-only`); Safetensors `__metadata__` note landed 2026-11-13 (`safetensors-sidecar-host-verify-only`, 3.3.0); DEX string-pool note landed 2026-11-13 nightly (`dex-sidecar-host-verify-only`, 3.3.1); SQLite schema-comment / reserved-VIEW note landed 2026-11-14 nightly (`sqlite-sidecar-host-verify-only`). Optional JS-loader hook (`generateSidecarWasmLoaderSnippet` / `prependWasmSidecarLoaderHook` / `entangleWasmLoaderWithSidecars`) landed 2026-11-15 nightly — host-opt-in, so `wasm-sidecar-host-verify-only` remains and `wasm-sidecar-entangle` is not recorded until a protect/harden path actually injects the hook into the customer's loader. Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks; auto-wire the WASM JS-loader hook when a loader path is known; MCP one-click polish.
2. **Sidecar entry entanglement** — JS strip⇒fail landed 2026-11-05; Python preamble landed 2026-11-06 nightly; WASM `bla.sidecar.v1` custom-section + host verify landed 2026-11-07 nightly; Bun `.bla-sidecar.v1.json` companion + defenseScore `sidecar-entangle-not-enabled` gap landed 2026-11-08 nightly; ASAR `.bla/sidecar.v1.json` archive-note landed 2026-11-09 nightly; ASAR main JS preamble landed 2026-11-10 nightly; `.pyc` TYPE_ASCII marshal trailer (host verify) landed 2026-11-11 nightly — **2026-11-12 honesty:** do not record `pyc-sidecar-entangle` / do not clear the strip⇒fail defenseScore gap until an import-time hook lands (`pyc-sidecar-host-verify-only`); GGUF STRING metadata note landed 2026-11-12 (`gguf-sidecar-host-verify-only`); Safetensors `__metadata__` note landed 2026-11-13 (`safetensors-sidecar-host-verify-only`, 3.3.0); DEX string-pool note landed 2026-11-13 nightly (`dex-sidecar-host-verify-only`, 3.3.1); SQLite schema-comment / reserved-VIEW note landed 2026-11-14 nightly (`sqlite-sidecar-host-verify-only`). Optional JS-loader hook (`generateSidecarWasmLoaderSnippet` / `prependWasmSidecarLoaderHook` / `entangleWasmLoaderWithSidecars`) landed 2026-11-15 nightly — host-opt-in, so `wasm-sidecar-host-verify-only` remains and `wasm-sidecar-entangle` is not recorded until a protect/harden path actually injects the hook into the customer's loader. **2026-11-16 honesty:** ESM static `import` / `export-from` bindings evaluate before the prepended sidecar/self-seal IIFE; annotate `esm-import-hoist-before-hooks` (soft-cap 93) and do not claim process-start for the hoisted graph. Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks; auto-wire the WASM JS-loader hook when a loader path is known; ESM loader hook that runs before hoisted imports; MCP one-click polish.
3. **Deception shields → more formats** — WASM export rename + `wasmPreserveExports` landed; DEX/SQLite/model densify and broader numeric template hygiene still open.
4. **Empirical JADX / Android red-team** — real REA mapping+JNI vs BLA-hardened unsigned APK.
5. **ESP flash / esp-image (#8228)** — if REA moved there; UF2 empirical red-team otherwise.
+2 -1
View File
@@ -1,6 +1,6 @@
# DESIGN: Sidecar / entry entanglement (issue #40 / STATE)
Status: **JS + Python + WASM + Bun companion + ASAR archive-note + ASAR main JS preamble strip⇒fail; .pyc marshal-note + GGUF STRING metadata note are host-verify only** — binding digest + JS/Python preambles + WASM `bla.sidecar.v1` custom-section note + Bun sibling `.bla-sidecar.v1.json` companion note (byte-exact binary) + ASAR in-archive `.bla/sidecar.v1.json` note + optional Electron main JS preamble (`generateSidecarAsarMainJsPreamble`) + CPython `.pyc` TYPE_ASCII marshal trailer (`generateSidecarPycMarshalNote` / `verifyPycSidecarMarshalNote`, importlib-ignored, no process-start fail) + GGUF `bla.sidecar.v1` STRING metadata KV (`generateSidecarGgufMetadataNote` / `verifyGgufSidecarMetadataNote`, alignment-safe rewrite keeps tensor bytes bit-exact; loaders ignore unknown STRING keys) + protect/harden opt-in landed; defenseScore gap when `sidecarEntangle` is off landed; `.pyc` / GGUF / Safetensors / DEX / SQLite host-only notes annotate `pyc-sidecar-host-verify-only` / `gguf-sidecar-host-verify-only` / `safetensors-sidecar-host-verify-only` / `dex-sidecar-host-verify-only` / `sqlite-sidecar-host-verify-only` and must not record the process-start vectors; optional JS-loader hook `generateSidecarWasmLoaderSnippet` / `prependWasmSidecarLoaderHook` / `entangleWasmLoaderWithSidecars` landed 2026-11-15 (host must prepend it into the loader that instantiates the module — `wasm-sidecar-host-verify-only` stays until that hook is actually wired; do not record `wasm-sidecar-entangle` yet). Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks.
Status: **JS + Python + WASM + Bun companion + ASAR archive-note + ASAR main JS preamble strip⇒fail; .pyc marshal-note + GGUF STRING metadata note are host-verify only** — binding digest + JS/Python preambles + WASM `bla.sidecar.v1` custom-section note + Bun sibling `.bla-sidecar.v1.json` companion note (byte-exact binary) + ASAR in-archive `.bla/sidecar.v1.json` note + optional Electron main JS preamble (`generateSidecarAsarMainJsPreamble`) + CPython `.pyc` TYPE_ASCII marshal trailer (`generateSidecarPycMarshalNote` / `verifyPycSidecarMarshalNote`, importlib-ignored, no process-start fail) + GGUF `bla.sidecar.v1` STRING metadata KV (`generateSidecarGgufMetadataNote` / `verifyGgufSidecarMetadataNote`, alignment-safe rewrite keeps tensor bytes bit-exact; loaders ignore unknown STRING keys) + protect/harden opt-in landed; defenseScore gap when `sidecarEntangle` is off landed; `.pyc` / GGUF / Safetensors / DEX / SQLite host-only notes annotate `pyc-sidecar-host-verify-only` / `gguf-sidecar-host-verify-only` / `safetensors-sidecar-host-verify-only` / `dex-sidecar-host-verify-only` / `sqlite-sidecar-host-verify-only` and must not record the process-start vectors; optional JS-loader hook `generateSidecarWasmLoaderSnippet` / `prependWasmSidecarLoaderHook` / `entangleWasmLoaderWithSidecars` landed 2026-11-15 (host must prepend it into the loader that instantiates the module — `wasm-sidecar-host-verify-only` stays until that hook is actually wired; do not record `wasm-sidecar-entangle` yet); **2026-11-16 honesty:** ESM static `import` / `export-from` bindings evaluate before the prepended JS IIFE — annotate `esm-import-hoist-before-hooks` (soft-cap 93); do not treat entry-body fail-closed as process-start for the hoisted graph. Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks; ESM loader hook that runs before hoisted imports.
## Goal
@@ -48,6 +48,7 @@ checks beat orphan honeypot files.
- ~~CPython `.pyc` marshal trailer note (host verify)~~ — 2026-11-11 nightly: `generateSidecarPycMarshalNote` / `bindPycSidecarEntanglement` / `entanglePycEntryWithSidecars` / `verifyPycSidecarMarshalNote`; TYPE_ASCII trailer after root (importlib-safe). **Honesty:** do not record `pyc-sidecar-entangle` until an import-time hook lands; defenseScore gap `pyc-sidecar-host-verify-only`. Default OFF.
- ~~GGUF STRING metadata note (host verify)~~ — 2026-11-12 nightly: `generateSidecarGgufMetadataNote` / `bindGgufSidecarEntanglement` / `entangleGgufEntryWithSidecars` / `verifyGgufSidecarMetadataNote`; `bla.sidecar.v1` STRING KV via alignment-safe `rebuildGguf` (tensor bytes bit-exact). **Honesty:** do not record `gguf-sidecar-entangle` until a load-time hook lands; defenseScore gap `gguf-sidecar-host-verify-only`. Also fixed `protectGgufBuffer` to use the same rewriter so tensor-bearing GGUFs no longer silently shift the data section. Default OFF. Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks.
- ~~JS runtime carrier honesty~~ — 2026-11-13: `.mjs`, `import`/`export`, top-level `await`, `import.meta`, and `.js` under nearest `package.json` `"type": "module"` are detected via Babel `program.sourceType` + `refineJsCarrierForRuntimePaths` and now receive an ESM-native strip⇒fail preamble (`import { createRequire } from "node:module"` + `import.meta.url`), with matching ESM `self-seal` support.
- **ESM import-hoist honesty** — 2026-11-16: the ESM-native preamble fail-closes the entry body, but static `import` / `export-from` bindings are instantiated first, so imported module side effects still run after sidecar strip or hook failure (`jsModuleHasHoistedDependencyGraph`; the BLA `createRequire` preamble import is ignored). Annotate defenseScore gap `esm-import-hoist-before-hooks` (soft-cap 93) when sidecar or self-seal is on. CJS `require()` after the preamble remains process-start. A true pre-import hook (custom ESM loader / `module.register` before the graph loads) is still TBD.
- ~~Safetensors `__metadata__` note (host verify)~~ — 2026-11-13: `generateSidecarSafetensorsMetadataNote` / `bindSafetensorsSidecarEntanglement` / `entangleSafetensorsEntryWithSidecars` / `verifySafetensorsSidecarMetadataNote`; `bla.sidecar.v1` `__metadata__` key keeps tensor bytes bit-exact; `defenseScore` annotates `safetensors-sidecar-host-verify-only` and `wasm-sidecar-host-verify-only` (soft-cap 93).
- ~~DEX string-pool note (host verify)~~ — 2026-11-13 nightly: `generateSidecarDexStringPoolNote` / `bindDexSidecarEntanglement` / `entangleDexEntryWithSidecars` / `verifyDexSidecarStringPoolNote`; unreferenced sort-last `bla.sidecar.v1=` pool string via `parseDexLayout` / `rebuildDex` (existing string indices + instruction bytes unchanged; trailers preserved). **Honesty:** do not record `dex-sidecar-entangle` until a load-time hook lands; defenseScore gap `dex-sidecar-host-verify-only`. Default OFF.
- ~~SQLite schema-comment / reserved-VIEW note (host verify)~~ — 2026-11-14 nightly: `generateSidecarSqliteSchemaComment` / `bindSqliteSidecarEntanglement` / `entangleSqliteEntryWithSidecars` / `verifySqliteSidecarSchemaComment`; unused `bla_sidecar_v1` VIEW (`SELECT '<json>' AS "bla.sidecar.v1" WHERE 0`) keeps user tables, rows, query results, WAL/FK, and application_id/user_version unchanged. **Honesty:** do not record `sqlite-sidecar-entangle` until a load-time hook lands; defenseScore gap `sqlite-sidecar-host-verify-only`. Default OFF. Remaining: `.pyc` import-time hook; GGUF/DEX/Safetensors/SQLite load-time hooks.
+1 -1
View File
@@ -109,7 +109,7 @@ Options:
--weave-decoys Opt-in structural weave decoys (Python customer-def / .pyc co_consts weave; JS AST weave already on); OFF by default
--self-seal Opt-in self-seal / sibling-module integrity binding for JS/Node targets (issue #40.5); OFF by default
--self-seal-sibling-glob <a,b> Comma-separated globs (cwd-relative) expanded into self-seal sibling paths; requires --self-seal (protect only)
--sidecar-entangle Opt-in sidecar/entry entanglement strip⇒fail for CommonJS & ESM JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40); OFF by default
--sidecar-entangle Opt-in sidecar/entry entanglement strip⇒fail for CommonJS & ESM JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40); ESM static imports still evaluate before the entry hook; OFF by default
--wasm-preserve-exports <a,b> Comma-separated WASM export names to keep as public ABI (issue #40.3)
--allow-lane-independent Allow harden/defend of lane-independent JS gates (issue #40.1); OFF by default
--allow-plaintext-seal Allow bankrupt harden despite plaintext/reversible seal JSON (round-2); OFF by default
+22
View File
@@ -24,6 +24,7 @@ export type DefenseScoreGapId =
| "dex-sidecar-host-verify-only"
| "sqlite-sidecar-host-verify-only"
| "wasm-sidecar-host-verify-only"
| "esm-import-hoist-before-hooks"
| "numeric-template-hygiene-partial"
| "native-postlink-cfg-untouched"
| "native-trailer-unmapped";
@@ -47,6 +48,11 @@ export interface DefenseScoreHonestyInput {
readonly numericTemplateLeakKnown?: boolean;
/** For post-link native binaries: true when decoys were planted into a mapped PT_LOAD / COFF section, false when trailer-only. */
readonly nativeMappedSectionInjected?: boolean;
/**
* True when a JS/TS ES module entry has static import / export-from bindings
* that the loader instantiates before a prepended sidecar / self-seal IIFE.
*/
readonly esmImportHoistBeforeHooks?: boolean;
}
export interface DefenseScoreHonesty {
@@ -189,6 +195,22 @@ export function collectDefenseScoreGaps(
});
}
// ESM static import / export-from bindings evaluate before any statement in
// the entry, including a prepended sidecarEntangle / self-seal IIFE. The
// entry body still fail-closes, but imported module side effects already ran.
if (
JS_LIKE.has(input.detectedFormat) &&
(input.sidecarEntangleEnabled === true || input.selfSealEnabled === true) &&
input.esmImportHoistBeforeHooks === true
) {
gaps.push({
id: "esm-import-hoist-before-hooks",
summary:
"ES module static import / export-from bindings evaluate before the prepended sidecarEntangle or self-seal IIFE, so imported module side effects still run after a sidecar strip or hook failure. Entry-body fail-closed is not process-start for the hoisted graph (issue #40 / DESIGN).",
scoreCap: 93,
});
}
if (input.numericTemplateLeakKnown === true) {
gaps.push({
id: "numeric-template-hygiene-partial",
+17
View File
@@ -13,6 +13,7 @@ import {
} from "./defense-score-honesty.js";
import { inspectNativeBinary } from "../shields/formats/native.js";
import { verifySelfSealSelfDigest } from "../shields/runtime/self-seal.js";
import { jsModuleHasHoistedDependencyGraph } from "../shields/javascript/ast-shield.js";
export interface VerifyTargetOptions {
readonly selfSealEnabled?: boolean;
@@ -167,6 +168,21 @@ export function verifyTarget(
}
}
let esmImportHoistBeforeHooks = false;
if (
afterAudit.detectedFormat === "javascript" ||
afterAudit.detectedFormat === "typescript"
) {
try {
esmImportHoistBeforeHooks = jsModuleHasHoistedDependencyGraph(
readFileSync(absTarget, "utf8"),
absTarget,
);
} catch {
esmImportHoistBeforeHooks = false;
}
}
const honesty = applyDefenseScoreHonesty(rawDefenseScore, {
detectedFormat: afterAudit.detectedFormat,
selfSealEnabled: effectiveSelfSealEnabled,
@@ -176,6 +192,7 @@ export function verifyTarget(
...(nativeMappedSectionInjected !== undefined
? { nativeMappedSectionInjected }
: {}),
...(esmImportHoistBeforeHooks ? { esmImportHoistBeforeHooks: true } : {}),
});
const agentActions: VerificationAgentAction[] = [];
+1
View File
@@ -25,6 +25,7 @@ export {
inferJsLoaderFromPath,
inferJsCarrierFromPath,
collectEsmExportedSymbols,
jsModuleHasHoistedDependencyGraph,
type JsCarrierType,
type JsLoaderType,
type JsTransformOptions,
+3 -3
View File
@@ -275,7 +275,7 @@ const RAW_BLA_MCP_TOOLS: readonly McpToolDefinition[] = [
sidecar_entangle: {
type: "boolean",
description:
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fails closed. OFF by default.",
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fail-closes the entry body. ESM static import/export-from bindings still evaluate before that hook (defenseScore gap esm-import-hoist-before-hooks). OFF by default.",
},
require_agent_weave: {
type: "boolean",
@@ -437,7 +437,7 @@ const RAW_BLA_MCP_TOOLS: readonly McpToolDefinition[] = [
sidecar_entangle: {
type: "boolean",
description:
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fails closed. OFF by default.",
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fail-closes the entry body. ESM static import/export-from bindings still evaluate before that hook (defenseScore gap esm-import-hoist-before-hooks). OFF by default.",
},
require_agent_weave: {
type: "boolean",
@@ -568,7 +568,7 @@ const RAW_BLA_MCP_TOOLS: readonly McpToolDefinition[] = [
sidecar_entangle: {
type: "boolean",
description:
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fails closed. OFF by default.",
"Opt-in sidecar/entry entanglement for JS/Python/ASAR + WASM/Bun/.pyc/GGUF/Safetensors notes (issue #40). When true, harden/protect binds sibling sidecar bytes into the entry via a strip⇒fail preamble (CommonJS require or ESM createRequire + import.meta.url) — removing or altering a sidecar fail-closes the entry body. ESM static import/export-from bindings still evaluate before that hook (defenseScore gap esm-import-hoist-before-hooks). OFF by default.",
},
wasm_preserve_exports: {
type: "array",
+54
View File
@@ -262,6 +262,60 @@ export function detectJsCarrierForSource(
}
}
/**
* True when an ES module has static `import` / `export-from` bindings that the
* ESM loader will instantiate *before* any statement in the file — including a
* prepended sidecarEntangle / self-seal IIFE. The BLA preamble's own
* `import { createRequire } from "node:module"` is ignored (it has no user
* side effects). CommonJS `require()` after a preamble is *not* hoisted.
*
* Honesty: entry-body fail-closed is not process-start for the hoisted graph.
*/
export function jsModuleHasHoistedDependencyGraph(
source: string,
filename?: string,
): boolean {
const loader = inferJsLoaderFromPath(filename);
const requested = inferJsCarrierFromPath(filename);
const parserSourceType =
requested === "module"
? "module"
: requested === "commonjs" || requested === "script"
? "script"
: "unambiguous";
try {
const ast = parse(source, {
sourceType: parserSourceType,
plugins: buildParserPlugins(loader, filename !== undefined),
errorRecovery: false,
});
if (ast.program.sourceType !== "module") return false;
return ast.program.body.some((stmt) => isHoistedUserModuleEdge(stmt));
} catch {
return false;
}
}
function isPreambleCreateRequireImport(stmt: t.Node): boolean {
if (!t.isImportDeclaration(stmt)) return false;
if (stmt.source.value !== "node:module") return false;
if (stmt.specifiers.length === 0) return false;
return stmt.specifiers.every(
(spec) =>
t.isImportSpecifier(spec) &&
t.isIdentifier(spec.imported) &&
spec.imported.name === "createRequire",
);
}
function isHoistedUserModuleEdge(stmt: t.Node): boolean {
if (isPreambleCreateRequireImport(stmt)) return false;
if (t.isImportDeclaration(stmt)) return true;
if (t.isExportAllDeclaration(stmt) && stmt.source !== null) return true;
if (t.isExportNamedDeclaration(stmt) && stmt.source !== null) return true;
return false;
}
export function collectEsmExportedSymbols(program: t.Program): string[] {
const exported: string[] = [];
for (const stmt of program.body) {
+199
View File
@@ -0,0 +1,199 @@
import { describe, expect, it } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync, unlinkSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { spawnSync } from "node:child_process";
import { protectTarget } from "../src/engine/protector.js";
import { verifyTarget } from "../src/engine/verifier.js";
import {
applyDefenseScoreHonesty,
collectDefenseScoreGaps,
} from "../src/engine/defense-score-honesty.js";
import { jsModuleHasHoistedDependencyGraph } from "../src/shields/javascript/ast-shield.js";
/**
* Red 2026-11-16: ESM static import / export-from bindings are instantiated
* before any statement in the entry, including the prepended sidecarEntangle
* / self-seal IIFE. Deleting a sidecar still fail-closes the entry body, but
* imported module side effects already ran. CJS require() after the preamble
* does not have this gap.
*/
function makeDir(prefix: string): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
return dir;
}
function runNode(file: string, cwd?: string) {
const env = { ...process.env };
delete env.NODE_OPTIONS;
return spawnSync(process.execPath, [file], { encoding: "utf8", env, cwd });
}
describe("jsModuleHasHoistedDependencyGraph", () => {
it("is false for CommonJS require graphs and for ESM entries without imports", () => {
expect(
jsModuleHasHoistedDependencyGraph(
'const { n } = require("./lib.js");\nconsole.log(n);\n',
"app.js",
),
).toBe(false);
expect(
jsModuleHasHoistedDependencyGraph(
'const n = await Promise.resolve(2);\nconsole.log(n);\n',
"app.js",
),
).toBe(false);
});
it("ignores the BLA createRequire preamble and flags user import / export-from", () => {
const preamble =
'import { createRequire as _resolveModuleRequire_deadbeef } from "node:module";\n(function(){})();\n';
expect(jsModuleHasHoistedDependencyGraph(preamble, "app.js")).toBe(false);
expect(
jsModuleHasHoistedDependencyGraph(
`${preamble}import { n } from "./lib.js";\nconsole.log(n);\n`,
"app.js",
),
).toBe(true);
expect(
jsModuleHasHoistedDependencyGraph('export { n } from "./lib.js";\n', "app.mjs"),
).toBe(true);
expect(jsModuleHasHoistedDependencyGraph('export const n = 1;\n', "app.mjs")).toBe(
false,
);
});
});
describe("defenseScore honesty: esm-import-hoist-before-hooks", () => {
it("annotates JS ESM entries with a hoisted graph when sidecar or self-seal is on", () => {
const off = collectDefenseScoreGaps({
detectedFormat: "javascript",
selfSealEnabled: true,
sidecarEntangleEnabled: true,
esmImportHoistBeforeHooks: false,
});
expect(off.map((g) => g.id)).not.toContain("esm-import-hoist-before-hooks");
const on = applyDefenseScoreHonesty(99, {
detectedFormat: "javascript",
selfSealEnabled: true,
sidecarEntangleEnabled: true,
esmImportHoistBeforeHooks: true,
});
expect(on.gaps.map((g) => g.id)).toContain("esm-import-hoist-before-hooks");
expect(on.cappedScore).toBe(93);
expect(on.appliedCap).toBe(93);
});
it("does not annotate the gap when neither sidecar nor self-seal is enabled", () => {
const gaps = collectDefenseScoreGaps({
detectedFormat: "javascript",
selfSealEnabled: false,
sidecarEntangleEnabled: false,
esmImportHoistBeforeHooks: true,
});
expect(gaps.map((g) => g.id)).not.toContain("esm-import-hoist-before-hooks");
});
});
describe("ESM sidecarEntangle hoist vs CJS process-start (red 2026-11-16)", () => {
it("ESM imported side effects still run after sidecar delete; entry body fail-closes; honesty gap is annotated", () => {
const dir = makeDir("bla-esm-hoist-");
try {
mkdirSync(join(dir, "in"));
mkdirSync(join(dir, "out"));
writeFileSync(join(dir, "in", "package.json"), JSON.stringify({ type: "module" }) + "\n");
writeFileSync(join(dir, "out", "package.json"), JSON.stringify({ type: "module" }) + "\n");
writeFileSync(join(dir, "in", "lib.js"), 'console.log("SIDEEFFECT");\nexport const n = 2;\n');
writeFileSync(join(dir, "out", "lib.js"), 'console.log("SIDEEFFECT");\nexport const n = 2;\n');
writeFileSync(
join(dir, "in", "app.js"),
'import { n } from "./lib.js";\nconsole.log("RESULT", n + 3);\n',
);
writeFileSync(join(dir, "out", "honey.txt"), "honey\n");
const before = runNode(join(dir, "in", "app.js"));
expect(before.status, before.stderr).toBe(0);
expect(before.stdout).toContain("SIDEEFFECT");
expect(before.stdout).toContain("RESULT 5");
protectTarget({
inputPath: join(dir, "in", "app.js"),
outputPath: join(dir, "out", "app.js"),
intensity: "balanced",
seed: "esm-import-hoist-red-20261116",
honeySourceMaps: false,
sidecarEntangle: true,
sidecarEntanglePaths: ["honey.txt"],
});
const intact = runNode(join(dir, "out", "app.js"));
expect(intact.status, intact.stderr).toBe(0);
expect(intact.stdout).toContain("SIDEEFFECT");
expect(intact.stdout).toContain("RESULT 5");
const verification = verifyTarget(join(dir, "out", "app.js"), join(dir, "in", "app.js"), {
sidecarEntangleEnabled: true,
});
expect(verification.defenseScoreGaps?.some((g) => g.id === "esm-import-hoist-before-hooks")).toBe(
true,
);
expect(verification.defenseScore).toBeLessThanOrEqual(93);
unlinkSync(join(dir, "out", "honey.txt"));
const stripped = runNode(join(dir, "out", "app.js"));
expect(stripped.status).not.toBe(0);
expect(stripped.stderr).toMatch(/integrity binding mismatch/i);
expect(stripped.stdout).toContain("SIDEEFFECT");
expect(stripped.stdout).not.toContain("RESULT");
expect(readFileSync(join(dir, "out", "app.js"), "utf8")).toContain("createRequire");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("CommonJS require graphs do not run imported side effects after sidecar delete, and the hoist gap stays off", () => {
const dir = makeDir("bla-cjs-hoist-ctrl-");
try {
mkdirSync(join(dir, "in"));
mkdirSync(join(dir, "out"));
writeFileSync(join(dir, "in", "lib.js"), 'console.log("SIDEEFFECT");\nmodule.exports = { n: 2 };\n');
writeFileSync(join(dir, "out", "lib.js"), 'console.log("SIDEEFFECT");\nmodule.exports = { n: 2 };\n');
writeFileSync(
join(dir, "in", "app.js"),
'const { n } = require("./lib.js");\nconsole.log("RESULT", n + 3);\n',
);
writeFileSync(join(dir, "out", "honey.txt"), "honey\n");
protectTarget({
inputPath: join(dir, "in", "app.js"),
outputPath: join(dir, "out", "app.js"),
intensity: "balanced",
seed: "cjs-import-hoist-ctrl-20261116",
honeySourceMaps: false,
sidecarEntangle: true,
sidecarEntanglePaths: ["honey.txt"],
});
const intact = runNode(join(dir, "out", "app.js"));
expect(intact.status, intact.stderr).toBe(0);
expect(intact.stdout).toContain("RESULT 5");
const verification = verifyTarget(join(dir, "out", "app.js"), join(dir, "in", "app.js"), {
sidecarEntangleEnabled: true,
});
expect(
verification.defenseScoreGaps?.some((g) => g.id === "esm-import-hoist-before-hooks") ?? false,
).toBe(false);
unlinkSync(join(dir, "out", "honey.txt"));
const stripped = runNode(join(dir, "out", "app.js"));
expect(stripped.status).not.toBe(0);
expect(stripped.stderr).toMatch(/integrity binding mismatch/i);
expect(stripped.stdout).not.toContain("SIDEEFFECT");
expect(stripped.stdout).not.toContain("RESULT");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});