Zum Inhalt springen
Jefferson Gonçalves
← Zurück zu den Projekten

Franken Native Capsule

#Franken Native Capsule

franken_native_capsule is the separately owned native-code mechanism for FrankenEngine. It contains no JavaScript parser, values, semantics, policy selection, replay policy, evidence-signing keys, or guest authority.

The production dependency direction is strictly:

franken_node -> franken_engine -> franken_native_capsule

The workspace has three packages:

  • frankenengine-native-capsule-api: safe, versioned lifecycle wire types and a provisional fixed-probe NRP/RCO v0 (#![forbid(unsafe_code)]). The broader production NRP/RCO v1 required by ADR-0010 is intentionally not claimed.
  • frankenengine-native-capsule: structural validation, executable-image lifecycle, relocation, platform adapters, and raw invocation. First-party unsafe is permitted only in the exact ADR-0010 module allowlist.
  • franken-native-capsule-worker: an authority-free compiler worker that emits sealed, address-free RCOs and never maps or executes them (#![forbid(unsafe_code)]).

The implementation follows /dp/franken_engine/docs/adr/ADR-0010-native-code-capsule-trust-boundary.md. The currently implemented fixed-probe path is bring-up evidence only: it is not JavaScript execution, is not enabled by FrankenEngine, and establishes no production containment or performance claim.

#Current executable slice

The opt-in embedded-fixed-probe feature enables one deliberately closed Linux x86-64-v3 path:

  • the safe worker lowers only the frozen wrapping sum-to-exclusive u64 -> u64 plan with Cranelift 0.134.2 and returns an opaque compilation object;
  • the runtime revalidates the exact plan, compiler identity, receipt, RCO seal, target, leaf metadata, entrypoint, authorization window/profile/epochs, and page-rounded executable-byte budget;
  • Linux maps a dedicated guard-page-surrounded region PROT_NONE -> RW -> RX, never RWX, and the only raw call site admits the exact System V leaf ABI;
  • input is bounded by the NRP before native entry; retirement removes execute, zeroes the complete middle mapping, unmaps it, and reports reclaimed bytes;
  • tests compare multiple native results with an independent wrapping oracle, inspect /proc/self/maps for RX-without-W, exercise refusal and nonce replay, and prove the retired address is no longer mapped.

The feature is off by default, so the ordinary runtime dependency graph does not include the compiler worker or Cranelift. It is not an IPC worker, issuer signature verifier, durable nonce store, process sandbox/supervisor, unwind or CFI registrar, JavaScript NRP lowering, deoptimizer, OSR path, or production router. In particular, elapsed/output limits are post-operation admission checks and the transient-memory field is not enforced without the missing external worker supervisor. Those remain separate prerequisites before any untrusted extension or performance-parity claim.

Neue Version verfügbar.