diff --git a/.agents/skills/blind-llm-agents/SKILL.md b/.agents/skills/blind-llm-agents/SKILL.md index e3a0bc2..51057bf 100644 --- a/.agents/skills/blind-llm-agents/SKILL.md +++ b/.agents/skills/blind-llm-agents/SKILL.md @@ -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: diff --git a/CHANGELOG.md b/CHANGELOG.md index ed69587..a8651e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/STATE.md b/STATE.md index 7233030..c2092d8 100644 --- a/STATE.md +++ b/STATE.md @@ -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. diff --git a/docs/design/sidecar-entry-entanglement.md b/docs/design/sidecar-entry-entanglement.md index 76bde97..4cc73c7 100644 --- a/docs/design/sidecar-entry-entanglement.md +++ b/docs/design/sidecar-entry-entanglement.md @@ -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 '' 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. diff --git a/src/cli.ts b/src/cli.ts index 1c0e5af..af68681 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -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 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 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 diff --git a/src/engine/defense-score-honesty.ts b/src/engine/defense-score-honesty.ts index aaeefa0..1ce2826 100644 --- a/src/engine/defense-score-honesty.ts +++ b/src/engine/defense-score-honesty.ts @@ -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", diff --git a/src/engine/verifier.ts b/src/engine/verifier.ts index 82899c9..50bd445 100644 --- a/src/engine/verifier.ts +++ b/src/engine/verifier.ts @@ -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[] = []; diff --git a/src/index.ts b/src/index.ts index 2911431..f221855 100644 --- a/src/index.ts +++ b/src/index.ts @@ -25,6 +25,7 @@ export { inferJsLoaderFromPath, inferJsCarrierFromPath, collectEsmExportedSymbols, + jsModuleHasHoistedDependencyGraph, type JsCarrierType, type JsLoaderType, type JsTransformOptions, diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 9276708..8a1e06d 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -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", diff --git a/src/shields/javascript/ast-shield.ts b/src/shields/javascript/ast-shield.ts index 9734d84..cf2c4c6 100644 --- a/src/shields/javascript/ast-shield.ts +++ b/src/shields/javascript/ast-shield.ts @@ -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) { diff --git a/tests/esm-import-hoist-honesty.test.ts b/tests/esm-import-hoist-honesty.test.ts new file mode 100644 index 0000000..2000ee7 --- /dev/null +++ b/tests/esm-import-hoist-honesty.test.ts @@ -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 }); + } + }); +});