engine.oracle

BYO decryption oracle loader.

Loads a user-supplied Python file that exposes either:

Shape 1 — stateless function:

def verify(candidate: bytes) -> bool: …

Shape 2 — stateful factory (amortizes KDF/socket setup):

def build_oracle(config: dict) -> Oracle:

return MyOracle(config)

class MyOracle:

def verify(self, candidate: bytes) -> bool: … def close(self): … # optional

Memdiver auto-detects the shape and always hands the caller a flat verify(bytes) -> bool callable.

Security: --oracle runs arbitrary Python with the caller’s privileges, equivalent to find -exec. This loader prints the sha256 of the loaded module to stderr and refuses to load oracles from world-writable paths.

class Oracle

Bases: Protocol

Stateful oracle shape produced by build_oracle(config).

verify(candidate)

Parameters:

candidate (bytes)

Return type:

bool

__init__(*args, **kwargs)

exception OracleLoadError

Bases: RuntimeError

Raised when a user oracle file cannot be loaded or validated.

load_oracle_config(path)

Load an optional TOML config file into a plain dict.

Parameters:

path (Path | None)

Return type:

dict[str, Any]

load_oracle(path, config=None)

Load a user oracle script and return a flat verify(bytes) -> bool.

Auto-detects Shape 1 (def verify(candidate)) vs Shape 2 (def build_oracle(config) -> Oracle). Shape 2 is preferred when the oracle needs to cache KDF state or open a network connection once; Shape 1 is fine for hot-path-only verifiers.

Raises OracleLoadError on missing files, unsafe permissions, import failures, or missing/invalid exports.

Parameters:

• path (Path | str)

• config (dict[str, Any] | None)

Return type:

Callable[[bytes], bool]