PRODUCTION-READINESS.md

# BEX Engine Production Readiness Audit

This document records the current production posture of `pluginengine01` after the HTTP/backend re-audit.

## Current Verdict

The engine is **usable in C/C++ desktop/server apps today** as a portable WASM plugin runtime with:

- Pure C ABI (`bex_engine.h`)
- Async callback API
- Wasmtime Component Model sandboxing
- Per-plugin manifests and capability gates
- HTTP host API with browser-like headers, cookies, compression, HTTP/2
- QuickJS host API for site-specific JavaScript/cipher code
- Redb-backed KV/secrets storage
- FlatBuffer/JSON conversion paths for C++ apps

The engine is **not yet a universal Cloudflare bypass engine**. The default HTTP backend is intentionally portable (`reqwest + rustls`) and does not byte-match Chrome's TLS JA3/JA4 fingerprint.

## Production-Safe Default Backend

Current default:

```toml
reqwest = { version = "0.12", default-features = false, features = [
  "rustls-tls", "json", "gzip", "brotli", "deflate", "cookies", "http2"
] }
```

Why this is the default:

- Builds reliably on Linux, macOS, Windows.
- Embeds cleanly into C/C++ apps.
- Avoids native BoringSSL/curl-impersonate build complexity.
- Keeps the repo buildable without unverified crate APIs.

Limitations:

- TLS fingerprint is rustls, not Chrome/BoringSSL.
- Advanced anti-bot systems may still challenge/block.
- Browser-like HTTP headers help with simple checks but do not fix JA3/JA4.

## Cloudflare / Anti-Bot Reality

| Protection type | Default backend | Notes |
|---|---:|---|
| Basic header checks | ✅ | Chrome-like headers, cookies, H2, compression |
| Cookie/session checks | ✅ | `cookie_store(true)` |
| Simple CF managed challenge | ⚠️ | Can pass some; not guaranteed due TLS fingerprint |
| CF JS challenge | ⚠️ | Requires plugin/QuickJS solver and session cookies |
| Turnstile/CAPTCHA | ❌ | Needs user interaction/WebView/browser handoff |
| DataDome/PerimeterX/Akamai bot | ❌/⚠️ | Usually requires Chrome TLS + H2 fingerprint impersonation |

## Optional Hardened HTTP Backend Roadmap

For real browser-grade anti-bot bypass, add an **optional Cargo feature**, not the default:

```toml
[features]
default = ["http-reqwest"]
http-reqwest = ["dep:reqwest"]
http-impersonate = ["dep:rquest"] # or another verified crate
```

Requirements before enabling this in production:

1. Verify crate/version exists and API compiles.
2. Verify Chrome profile enum/import path.
3. Verify Linux/macOS/Windows build in CI.
4. Verify cross-compilation for app targets.
5. Verify TLS fingerprint on every target with an external JA3/JA4 tester.
6. Keep `reqwest` fallback for platforms where impersonation cannot build.

Do **not** ship an unverified `rquest = "1.0"` or undocumented builder API.

## C++ App Integration Status

### Good

- ABI is plain C, no Rust types across boundary.
- Callbacks return `payload` plus length; C++ can copy before return.
- Sync plugin management functions use integer status codes.
- Strings returned by Rust have explicit free functions.
- CMake now supports macOS/Linux/Windows better and no longer forces full static glibc linking.

### Integration Rules

C++ apps must:

1. Keep `BexEngine*` alive until all callbacks complete.
2. Keep `user_data` alive until callback fires or request is cancelled and callback path is known.
3. Copy callback payload before returning from callback.
4. Marshal callback results to the app/UI thread if needed.
5. Call `bex_engine_free` only during shutdown, not while new requests are being submitted.

## Known Issues To Fix Before Hard Production

These are not architecture blockers, but should be addressed before high-volume deployment:

1. **Cancellation tokens should be removed after async task completion.**
   - Current code inserts tokens but does not visibly remove them in `submit_async` after completion.
   - Long-running apps may leak entries in the cancellation map.

2. **`bex_engine_secret_get` should guard zero-length buffers.**
   - If caller passes `*out_buf_len == 0`, `buf_size - 1` underflows.
   - Add explicit `if buf_size == 0 { required_len = value.len()+1; return -2; }`.

3. **Scheduler exists but FFI async submit path does not visibly acquire scheduler permits.**
   - The architecture has lane semaphores, but `submit_async` currently uses `spawn_blocking` directly.
   - Add scheduler acquisition around user/control/background calls for true production backpressure.

4. **HTTP cache key is URL-only.**
   - If two plugins request the same URL with different auth headers, cached response can cross-contaminate.
   - Make key `plugin_id + method + url + vary-relevant headers`, or disable cache for requests with auth/cookie-sensitive headers.

5. **`call-js-fn` should resolve Promises like `eval-js`.**
   - Async JS functions returning promises may stringify as `{}`.
   - Reuse the Promise resolution logic from `eval_js` in `worker.rs`.

## Plugin Architecture Assessment

The WIT interface is sufficient for multi-site media plugins:

- home/category/search/info/servers/stream
- subtitles/articles
- HTTP with headers/body/method/cache mode
- KV/secrets
- QuickJS for ciphers/player scripts
- logging/clock/rng

The KaiAnime plugin proves the model works end-to-end:

- HTML scraping
- AJAX endpoints
- self-describing episode IDs
- multi-step token encryption/decryption
- server listing
- stream resolution
- HLS + subtitles

However, KaiAnime currently depends on `enc-dec.app` instead of local QuickJS cipher code. For long-term reliability, move site ciphers into plugin-local JS via `call-js-fn`.

## Cross-Platform Matrix

| Target | Current default backend | Status |
|---|---:|---|
| Linux x86_64 | reqwest/rustls | ✅ Good |
| Linux aarch64 | reqwest/rustls | ✅ Good |
| macOS x86_64/arm64 | reqwest/rustls | ✅ Good, CMake framework links added |
| Windows MSVC | reqwest/rustls | ✅ Likely, system libs added |
| Android | Rust staticlib possible | ⚠️ Needs NDK CI proof |
| iOS | Rust staticlib possible | ⚠️ Needs iOS toolchain + Wasmtime support verification |
| Fully static Linux glibc | Not default | ⚠️ Opt-in only via `BEX_FORCE_STATIC_EXE=ON` |

## Recommendation

For production apps today:

1. Use the current default backend for portability.
2. Add CI for Linux/macOS/Windows release builds.
3. Fix the five known issues above.
4. Add optional impersonation backend later, behind a feature flag, only after compile/API/fingerprint verification.
5. For sites with serious bot defenses, provide app-level browser/WebView handoff as fallback.