Metadata-Version: 2.4
Name: nxd
Version: 0.3.5
Summary: Encrypted compute layer for AI agents
Author: Nexplora Labs
License-Expression: LicenseRef-Nexplora-Proprietary
Project-URL: Homepage, https://github.com/Nexploraai/nxd
Project-URL: Repository, https://github.com/Nexploraai/nxd
Project-URL: Issues, https://github.com/Nexploraai/nxd/issues
Keywords: fhe,encryption,ai-agents,privacy,homomorphic-encryption
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: mcp>=1.28.1
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: portalocker>=3.2.0
Requires-Dist: scikit-learn>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: fhe
Requires-Dist: concrete-ml==1.9.0; extra == "fhe"
Dynamic: license-file

# NXD

NXD is an encrypted compute layer for AI agents. It wraps fully homomorphic encryption, credential vaulting, and privacy primitives behind a single Python import — so developers can run agents on sensitive data without exposing client records, credentials, or proprietary code to models, clouds, or MCP servers.

## Three guarantees

1. **The agent works fully** — capability unchanged; scores, matches, charges, and aggregates complete normally.
2. **The agent sees nothing** — when `shield()` is used, sensitive values stay encrypted and agents handle opaque tokens and references only.
3. **The operator holds the keys** — keys stay local, auditable, and revocable.

Agent sees nothing when `shield()` is used. `redact()` reduces exposure but is not a guarantee.

## Install

```bash
export NXD_OPERATOR_PASSPHRASE="choose-a-long-random-passphrase"
pip install nxd
```

Requires Python 3.10 or 3.11 (Concrete ML FHE dependency).

## Quick start

```python
import nxd

# 1. Shield code before any AI call
code = "api_key = 'sk_live_xxxx'"
shielded = nxd.shield(code)
recovered = nxd.unshield(shielded)
print(f"AI sees:  {shielded[:40]}...")
print(f"You see:  {recovered}")
print(f"Match:    {code == recovered}")

# 2. Redact PII before sending to AI
note = "Patient John Smith, DOB 1985-04-12, SSN 432-11-5678"
clean, mapping = nxd.redact(note)
print(f"\nAI gets:  {clean}")
print(f"Original: {nxd.deredact(clean, mapping)}")

# 3. Vault a credential — agent never sees it
vault = nxd.Vault(agent_id="my-agent")
vault.store("stripe_key", "sk_live_xxxx")
result = vault.use("stripe_key", lambda k: f"charged via {k[:8]}...")
print(f"\nAgent got: {result}")
print("Key seen:  never")

# 4. Verify tamper-proof audit chain
nxd.audit.log("session", agent_id="my-agent")
print(f"\nAudit valid: {nxd.audit.verify()}")
```

## Vault safety

> ⚠️ IMPORTANT: `vault.use()` protects your credential in storage and transit. It cannot prevent your callback from returning plaintext.
>
> Safe:
> `vault.use("stripe_key", lambda k: stripe.charge(k))`
>
> Unsafe — leaks key to caller:
> `vault.use("stripe_key", lambda k: {"key": k, "status": "ok"})`
>
> Rule: callbacks should USE the credential, not RETURN it.

## Redaction

`redact()` returns both the safe text and the local restoration mapping:

```python
import nxd

safe, mapping = nxd.redact("Patient John Smith, SSN 432-11-5678")
restored = nxd.deredact(safe, mapping)
```

`mapping` stores the original values locally so you can restore them with `nxd.deredact(safe, mapping)`.

> ⚠️ `redact()` uses pattern-based detection.
> It catches common PII formats: names, SSNs,
> emails, phone numbers, dates, addresses,
> API keys, physician names, account numbers.
>
> It will miss: unusual formats, domain-specific
> identifiers, PII embedded in code logic,
> or context-dependent sensitive information.
>
> Rule: use `redact()` to reduce exposure,
> not as a guaranteed wall. For complete
> protection, combine with `shield()` which
> encrypts the entire payload regardless
> of content.

## Handoff tokens

Handoff tokens are single-use. A token that has already been unpacked raises `ReplayError` if it is unpacked again.

```python
import nxd

handoff = nxd.Handoff()
token = handoff.pack({"client": "Jane Doe", "balance": 50000})
payload = handoff.unpack(token)
```

For multi-agent workflows where the same context is needed by multiple agents, pack a separate token for each agent.

## Audit export

```python
import nxd

# Export a compliance report
nxd.audit.export("audit_report.json")
# Creates audit_report.json with full chain proof
# No sensitive values included in export
```

## Benchmarks (MacBook Air, Python 3.11, Concrete ML 1.9.0)

| Operation | Latency | Notes |
|-----------|---------|-------|
| FHE score (1 record) | ~183 ms | First-call cold start |
| FHE score (1k records, parallel) | **1.6 s** | 8 cores, ~1.6 ms/record |
| FHE match (single pair) | **352 ms** | Cross-system comparison |
| FHE aggregate (1k records, parallel) | **1.8 s** | ~0.009% quantization error |
| Credential vault use | <1 ms | Decrypt in memory only |
| Proof suite | **85/85 passed** | `python3 prove.py` |

## What NXD does not protect against

NXD protects credentials and sensitive data from AI providers, model context, and ordinary cloud exposure. It does not remove the need for normal endpoint security and key management discipline.

Local key custody: `master.key` lives on your machine. If your machine is compromised, keys are at risk. Hosted key management via HashiCorp Vault and AWS KMS is coming in v0.4.0 for production deployments.

NXD can prevent a model from seeing plaintext inputs. It does not control what a model does with the encrypted or redacted results it receives, so output handling still matters.

NXD uses FHE for specific compute operations such as `score`, `match`, and `aggregate`. It does not run the full LLM context window under FHE. For prompt and code protection, use `redact()` and `shield()`.

The local `master.key` model is suitable for development and small deployments. Production systems should use a managed key system such as HashiCorp Vault or AWS KMS. `nxd.Vault(hosted=True)` is planned for v0.4.0.

NXD helps protect against external providers and cloud exposure. It does not protect against a trusted operator with physical access, because that operator holds the keys by design.

Current encryption choices are not presented as quantum-resistant. Post-quantum primitives are on the roadmap, but they are not part of the current release.

`redact()` is best-effort pattern detection for common PII and secret formats. It reduces exposure, but it is not a guaranteed wall and will miss some sensitive values.

`blur()` uses calibrated Laplace privacy noise with explicit `epsilon` and `sensitivity` inputs. The helper is suitable for internal privacy-noise workflows, but formal differential-privacy claims for regulated deployments should follow an external review of the implementation and your parameter choices.

`split()` adds tamper detection to Shamir-style key splitting, but formal secret-sharing assurances should likewise be covered by external review before carrying a security certification claim.

NXD has completed an internal security review including:
- Adversarial testing of all primitives
- Cross-validation of Shamir implementation against `sslib`
- Statistical validation of differential privacy (KS-test vs `diffprivlib`)
- Randomness audit (no weak RNG found)
- MCP plaintext regression confirmed closed

`split` and `blur` are pending external cryptographic review. All other primitives wrap vetted libraries (`Fernet`, `Ed25519`, `PBKDF2`, `Concrete ML`).

## Roadmap

### v0.4.0 — Hosted Key Management

- `nxd.Vault(hosted=True)`
- HashiCorp Vault and AWS KMS backends
- Keys never touch operator disk
- Designed for production multi-machine deployments

### v0.5.0 — External Cryptographic Audit

- Independent review of `split` and `blur` implementations
- Formal security certification
- Required before regulated data production use

### v0.6.0 — Hardware Acceleration

- FHE operations on GPU/TPU
- Target: sub-10ms encrypted inference
- Enables real-time FHE for high-frequency operations

## Operator workflow

Set `NXD_OPERATOR_PASSPHRASE` before using the vault, audit chain, signatures, or any operator-only reveal flow. NXD stores ciphertext at rest, and the local key files are now wrapped with a PBKDF2-derived key from that operator passphrase.

When you use `nxd init`, NXD can vault `.env` secrets, replace them with `NXD_VAULT::NAME` references, and write an encrypted `.env.backup.nxd` recovery file.

On the MCP path, decrypt-style tools such as `nxd_unshield`, `nxd_unseal_text`, and `nxd_detokenize` no longer return plaintext to the agent. They queue an operator-only reveal:

```bash
nxd reveal <reveal_id>
```

## Development

```bash
git clone https://github.com/Nexploraai/nxd
cd nxd
pip install -e ".[dev]"
python3 prove.py
python3 agent.py
python3 demo.py
```

## License

Proprietary — Nexplora Labs. Free to use in projects, but the source may not be
modified, redistributed, resold, or used to build a competing encryption or
agent-protection product. See [LICENSE](LICENSE).
