Metadata-Version: 2.4
Name: qiskit-qkd-lab
Version: 0.2.0
Summary: A QKD protocol simulator built on Qiskit primitives, with circuit-level eavesdropping models.
Project-URL: Homepage, https://github.com/RexRowan/qiskit-qkd-lab
Project-URL: Issues, https://github.com/RexRowan/qiskit-qkd-lab/issues
Project-URL: Changelog, https://github.com/RexRowan/qiskit-qkd-lab/blob/main/CHANGELOG.md
Author-email: Rex Rowan <4164511+RexRowan@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bb84,cryptography,qiskit,qkd,quantum,quantum-key-distribution
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: qiskit-aer>=0.15
Requires-Dist: qiskit>=2.0
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# qiskit-qkd-lab

[![Tests](https://github.com/RexRowan/qiskit-qkd-lab/actions/workflows/test.yml/badge.svg)](https://github.com/RexRowan/qiskit-qkd-lab/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Qiskit](https://img.shields.io/badge/Qiskit-%3E%3D2.0-6929C4)](https://github.com/Qiskit/qiskit)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)

A QKD protocol simulator built directly on Qiskit primitives. Circuits run
unchanged on `AerSimulator` or on real IBM Quantum hardware — including
Eve's eavesdropping, which is implemented as genuine circuit operations
(mid-circuit measurement + reset + conditional re-prep), not a statevector
shortcut.

## Installation

```bash
pip install qiskit-qkd-lab
```

Requires **Qiskit 2.0 or later**. For local development or to run the
test suite:

```bash
git clone https://github.com/RexRowan/qiskit-qkd-lab.git
cd qiskit-qkd-lab
pip install -e ".[dev]"
pytest
```

## Quick start (Colab)

```python
from qiskit_qkd_lab.protocols import bb84
from qiskit_qkd_lab.channel.eavesdrop import InterceptResend
from qiskit_qkd_lab.diagnostics.qber import estimate_qber, key_rate_report
```

Or just run `examples/demo_bb84.py` directly — it's self-contained and
prints a QBER report for clean, fully-intercepted, and partially-intercepted
channels.

See [`docs/api.md`](docs/api.md) for the full API reference and a runnable
end-to-end example.

## Status

This package implements the measurement and diagnostics half of BB84.
Implemented so far:

- [x] BB84 prepare/measure circuits (Z/X basis)
- [x] Intercept-resend eavesdropper, circuit-level (mid-circuit measurement)
- [x] Sifting
- [x] QBER estimation via public sample comparison
- [x] Basic key-rate / Eve-detection report
- [x] Test suite + CI (Python 3.10–3.13)

Not yet implemented:

- [ ] E91 (entanglement-based) protocol
- [ ] Beam-splitting eavesdropper
- [ ] Cascade error reconciliation (currently we just sacrifice bits to
      *estimate* QBER; there's no actual error-correction step reconciling
      the retained key yet)
- [ ] Privacy amplification (universal hashing)
- [ ] Realistic channel noise model (fiber loss / detector dark counts)
- [ ] Live diagnostics dashboard (QBER vs. sample size, key rate vs.
      distance) — reusing patterns from `qiskit-sqd-dashboard`

**Because reconciliation and privacy amplification aren't implemented yet,
the "final key" this package produces is a sifted, QBER-estimated bit
string, not a cryptographically secure key.** It's a faithful simulator of
BB84's quantum layer and QBER-based eavesdropping detection, useful for
teaching and prototyping — treat it accordingly until those pieces land.

See [`CHANGELOG.md`](CHANGELOG.md) for release history and the roadmap.

## Design notes

- Eve's classical register (`eve`) is entirely separate from Alice/Bob's
  shared register (`c`) — Bob's measurement pipeline never touches it,
  which is what makes this a faithful "Eve is undetectable except through
  QBER" model rather than a leak.
- `InterceptResend(p_intercept=...)` lets you sweep partial interception
  to reproduce the textbook QBER-vs-intercept-rate curve, rather than only
  the full-intercept extreme.
- `n_qubits` in the demo means independent single-photon sends batched
  into one circuit for simulation speed — no entangling gates between
  them, so this maps directly onto real hardware qubit count budgets.

## Contributing

Contributions are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for
setup instructions, style guidelines, and the design principles this
project tries to hold to. Please note this project follows the
[Contributor Covenant](CODE_OF_CONDUCT.md).

## License

[MIT](LICENSE)
