Metadata-Version: 2.4
Name: fhe-oracle
Version: 0.1.1
Summary: Adversarial precision testing for FHE programs
Author-email: Bader Issaei <b@vaultbytes.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/BAder82t/fhe-oracle
Project-URL: Issues, https://github.com/BAder82t/fhe-oracle/issues
Project-URL: Commercial, https://vaultbytes.com/cipherexplain
Keywords: fhe,homomorphic-encryption,ckks,testing,cma-es,adversarial
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cma>=3.3.0
Requires-Dist: numpy>=1.22.0
Provides-Extra: openfhe
Requires-Dist: openfhe; extra == "openfhe"
Provides-Extra: concrete
Requires-Dist: concrete-ml>=1.0.0; extra == "concrete"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# FHE Oracle

Adversarial precision testing for Fully Homomorphic Encryption.
Finds CKKS bugs that random testing misses.

## Install

```bash
pip install fhe-oracle
```

## 30-second example

```python
import numpy as np
from fhe_oracle import FHEOracle

def plaintext_fn(x):
    return float(np.sum(np.asarray(x) ** 2))

def fhe_fn(x):
    # Stand-in for your FHE-compiled predict function.
    # Here: noise scales with input norm^2 (a CKKS depth-noise pattern),
    # with a hot zone that inflates the error 100x when |x|^2 > 8.
    v = float(np.sum(np.asarray(x) ** 2))
    base = 1e-5 * v
    amp = 100.0 if v > 8.0 else 1.0
    return plaintext_fn(x) + base * amp

oracle = FHEOracle(
    plaintext_fn=plaintext_fn,
    fhe_fn=fhe_fn,
    input_dim=4,
    input_bounds=[(-3.0, 3.0)] * 4,
    seed=0,
)
result = oracle.run(n_trials=300, threshold=1e-3)
print(result.verdict)      # "FAIL"
print(result.max_error)    # ~3.6e-2
print(result.worst_input)  # ~[3.0, 3.0, 3.0, -3.0]
```

Output:

```
OracleResult(verdict='FAIL', max_error=3.593336e-02, trials=304, elapsed=0.05s)
```

Swap the fixture for a real `fhe_fn` (e.g. `concrete-ml`'s
`predict_proba(x, fhe="execute")`) and the oracle will search
adversarially for inputs that break precision.

## Why this exists

FHE precision bugs are **input-localised**. A CKKS circuit that passes
on 99,999 random inputs in a row can return garbage on the 100,000th.
The inputs that trigger failure sit in narrow regions of the input
space — regions that scale with multiplicative depth and the
magnitude of intermediate ciphertexts — and those regions are vanishingly
unlikely to be hit by uniform random sampling.

Random testing wastes evaluations in safe parts of the input space.
An adversarial optimiser (CMA-ES, guided by a noise-budget-aware
fitness function) spends its budget climbing toward the failure
region instead, and finds bugs orders of magnitude larger than random
sampling in the same wall-clock budget.

In the published evaluation on a real CKKS logistic regression
circuit, the oracle found divergence **4,259×** larger than random
sampling at the same budget. See the patent specification and
accompanying paper referenced below for methodology.

## How it works

- **CMA-ES search** over the input domain, guided by a noise-aware
  fitness that combines plaintext/FHE divergence with ciphertext
  noise-budget consumption and multiplicative-depth utilisation.
- **Adapters** for OpenFHE, Concrete ML, and SEAL turn on
  noise-guided search. A pure divergence fallback works without any
  native FHE library — useful for CI.
- **Output**: PASS/FAIL verdict, worst input, sensitivity map, and a
  structured JSON/Markdown report for artefact upload.

## Benchmarks

See [benchmarks/](./benchmarks/README.md) for reproducible circuits:

| Circuit | Dim | Random max error | Oracle max error | Ratio |
|---------|-----|------------------|------------------|-------|
| Logistic regression (mock CKKS) | 8 | 2.7e-1 | 6.0e-1 | 2.2× |
| Polynomial (depth 4) | 6 | 1.7e-2 | 2.1e-2 | 1.3× |
| Dense + Chebyshev sigmoid | 10 | — | 1.0e-1 | — |

Each benchmark runs in under one second on a 2020-era laptop.

On a real CKKS implementation (not a mock), the published finding is
**4,259× larger divergence** than random sampling at the same budget.

## CI/CD integration

Drop `oracle_check.py` at your repo root:

```python
import os
from fhe_oracle import FHEOracle
from my_model import plaintext_fn, fhe_fn

oracle = FHEOracle(
    plaintext_fn=plaintext_fn,
    fhe_fn=fhe_fn,
    input_dim=10,
    input_bounds=[(-3.0, 3.0)] * 10,
)
result = oracle.run(
    n_trials=int(os.environ.get("ORACLE_N_TRIALS", "500")),
    threshold=float(os.environ.get("ORACLE_THRESHOLD", "0.01")),
)
print(result)
raise SystemExit(0 if result.verdict == "PASS" else 1)
```

Add `.github/workflows/fhe-precision.yml`:

```yaml
name: FHE Precision Test
on: [push, pull_request]

jobs:
  fhe-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pip install fhe-oracle
      - run: python oracle_check.py
        env:
          ORACLE_THRESHOLD: "0.01"
          ORACLE_N_TRIALS: "500"
```

Full template: [examples/github_action.yml](./examples/github_action.yml).

## Patent notice

A patent application covering this method has been filed
(**PCT/IB2026/053378**, "System and Method for Adversarial
Noise-Guided Differential Testing of Fully Homomorphic Encryption
Programs"). The open-source code here is licensed under **AGPL-3.0**.
Commercial licences are available at
[vaultbytes.com/cipherexplain](https://vaultbytes.com/cipherexplain).

## Related work

- **PCT/IB2026/053378** — FHE Differential Testing Oracle (this
  project's patent application)
- **[CipherExplain](https://vaultbytes.com/cipherexplain)** — full
  encrypted SHAP suite, homomorphic SHAP, DP privacy, EU AI Act
  compliance tooling
- **[PermNet-RM](https://github.com/BAder82t/PermNet-RM)** —
  permutation-equivariant reward models

## Contact

b@vaultbytes.com
