Metadata-Version: 2.4
Name: qids
Version: 1.3.4
Summary: Quantum digital signatures (one-time universal hashing) with a REST/gRPC gateway, Python client and quantum-link threat detection
License: Proprietary
Keywords: quantum-cryptography,quantum-digital-signature,post-quantum,threat-detection,quantum-teleportation,information-theoretic-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pyflakes>=3.0; extra == "dev"
Provides-Extra: hardware
Requires-Dist: quantum-debugger>=0.9.0; extra == "hardware"
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7; extra == "plots"
Provides-Extra: server
Requires-Dist: stripe>=9.0; extra == "server"
Requires-Dist: grpcio>=1.60; extra == "server"
Requires-Dist: protobuf>=7.35.1; extra == "server"
Dynamic: license-file

# QIDS — Quantum Digital Signatures Python SDK

[![PyPI version](https://img.shields.io/pypi/v/qids.svg)](https://pypi.org/project/qids/)
[![Python versions](https://img.shields.io/pypi/pyversions/qids.svg)](https://pypi.org/project/qids/)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)

**Quantum Digital Signatures (QDS) & Post-Quantum Security Platform**

`qids` is the official Python SDK for integrating Quantum Digital Signatures into banking transactions, enterprise document signing, and post-quantum zero-trust infrastructure.

---

## What is QIDS?

QIDS signs documents with **one-time universal hashing (OTUH)**, a quantum digital signature scheme. Its forgery bound (about 10⁻³⁷ for a typical document, returned with every signature) is **information-theoretic**: it assumes nothing about an attacker's computing power, classical or quantum, so Shor's algorithm, which breaks RSA and ECDSA, does not apply.

That bound holds for a one-time key that is uniformly random and secret, so where the key comes from matters:

- **Key from a QKD system** (over ETSI GS QKD 014): the guarantee holds end to end.
- **Key from the OS CSPRNG** (the default): the guarantee rests on that generator and is computational in practice.

Every signature states which source it used. The gateway deals the verifiers' key shares itself, so it is a trusted dealer: its guarantees are only as strong as the host it runs on.

---

## How It Works (High-Level Architecture)

QIDS operates via a secure 3-stage pipeline:

```
[ ETSI GS QKD 014 Key Stream / KMS ]
                 │
                 ▼
     ┌───────────────────────┐
     │ 1. Quantum Key Ingest │
     └───────────┬───────────┘
                 │
                 ▼
     ┌───────────────────────┐         Payload + One-Time Tag
     │ 2. Signature Creation ├─────────────────────────────────────────┐
     └───────────────────────┘                                         │
                                                                       ▼
                                                           ┌───────────────────────┐
                                                           │ 3. Fast Verification  │
                                                           │   (~4 ms, measured)   │
                                                           └───────────┬───────────┘
                                                                       │
                                                                       ▼
                                                             [ ACCEPT / REJECT ]
```

1. **Entropy Ingestion**: Syncs quantum key material from carrier-grade QKD links or local secure modules via ETSI GS QKD 014 standards.
2. **One-Time Signature Tagging**: Creates cryptographic tags binding document payloads to quantum key states.
3. **Deterministic Verification**: Verifiers independently confirm authenticity and non-repudiation using closed-form statistical verification (100% deterministic, zero ML hallucinations). Measured at ~4 ms per verification; see Performance below.

---

## Installation

```bash
pip install qids
```

*Requirements: Python 3.10 or higher.*

---

## Running QIDS (Docker)

Three ways to run the gateway, all with the same image (`deploy/vps/Dockerfile.gateway`):

| Target | File | What it runs |
| :--- | :--- | :--- |
| **Local stack** | [`docker-compose.yml`](docker-compose.yml) | The gateway (REST, gRPC, web console), a **mock** ETSI GS QKD 014 KMS feeding it keys, and Prometheus + Grafana with the QIDS dashboard provisioned. |
| **Internet-facing server** | [`deploy/vps/docker-compose.yml`](deploy/vps/docker-compose.yml) | The gateway behind Caddy with automatic TLS. See [`deploy/vps/README.md`](deploy/vps/README.md). |
| **Kubernetes** | [`deploy/helm/qids`](deploy/helm/qids) | One gateway replica with a persistent volume and its secrets. See the [operator guide](docs/USER_AND_OPERATOR_GUIDE.md#kubernetes). |

Local stack:

```bash
QIDS_METRICS_TOKEN=$(openssl rand -hex 16) docker compose up -d --build
# Gateway + console: http://localhost:8080/dashboard   (REST)  ·  localhost:50051 (gRPC)
# Grafana:           http://localhost:3000   ·   Prometheus: http://localhost:9090
```

The mock KMS serves CSPRNG keys and says so: its signatures report `entropy_source: "ETSI-GS-QKD-014-MOCK"` and `qkd_backed: false`.

---

## Quickstart

### High-Level Enterprise Client

```python
from qids import QIDSClient

# Signing happens on the Gateway, which holds the one-time key material.
# Get an API key from <gateway>/signup.
client = QIDSClient(
    node_id="bank_node_alpha",
    qids_service_url="https://your-gateway.example.com",
    api_key="sk_live_...",
)

# 1. Sign a transaction or document payload
payload = b"TRANSFER 1,000,000 USD TO ACCT-48910"
signature = client.sign(
    document_id="DOC-98104",
    payload=payload,
    recipient_ids=["bank_node_beta"],
)

print(f"Signed document {signature.document_id}")
print(f"Generated {len(signature.signature_tags)} recipient tag(s)")

# 2. Designated recipient verifies signature
verification = client.verify(
    document_id=signature.document_id,
    payload=payload,
    sender_id="bank_node_alpha",
    signature_tag=signature.signature_tags[0],
)

print(f"Verdict: {verification.reason} | threat: {verification.threat}")
# Output: Verdict: ok | threat: benign
# A tampered payload returns: reason "digest_mismatch", threat "forgery"
```

### Low-Level Session Execution

A simulation of the full teleportation-based protocol (Alice signs; Bob and
Charlie verify), not a network call:

```python
import numpy as np
from qids import QdsSession, ProtocolParams

session = QdsSession(params=ProtocolParams(key_length=1200), rng=np.random.default_rng(7))
result = session.run_benign()

for verifier, verdict in result.verdicts.items():
    print(verifier, verdict.decision)
# bob ACCEPT
# charlie ACCEPT
```

---

## Core Capabilities

- **Non-repudiation with dispute resolution**: every signature has a tenant-scoped audit receipt and Merkle root. Disputes between verifiers go through cross-verification (`/api/v1/cross-verify`).
- **Measured throughput** (developer laptop, full durability, SQLite persistence):
  - Signing engine: about 1,950 signatures/s.
  - HTTP API: about 570 requests/s with 4 gateway processes, about 900 with relaxed fsync.
  - Verification: about 236/s per process.
  - This suits document and transaction signing, not high-frequency trading. Method and history are in [the audit](docs/AUDIT_CLAIMS_VS_REALITY.md#1-performance-the-headline-numbers-were-not-measured).
- **ETSI GS QKD 014**: takes keys from any KMS that speaks this API. It has been tested against the bundled mock, not against QKD hardware.
- **REST and gRPC**: the same engine, receipts and metrics on both transports.
- **Auditable and deterministic**: no AI/ML models anywhere in the verification path.
## Multi-Language Ecosystem

QIDS provides client libraries across all major backend and systems languages. Four are **signing clients** that talk to the Gateway; three are **primitive libraries** (constant-time comparison, Toeplitz hashing, Wald SPRT) without a signing path:

| Language | Registry / Install | Repository |
| :--- | :--- | :--- |
| **Python** | `pip install qids` | [PyPI](https://pypi.org/project/qids/) |
| **TypeScript / Node.js** | `npm install qids-sdk` | [npm](https://www.npmjs.com/package/qids-sdk) |
| **Rust** *(primitives)* | `cargo add qids` | [crates.io](https://crates.io/crates/qids) |
| **Go** | `go get github.com/Raunakg2005/qids-go@v1.3.4` | [qids-go](https://github.com/Raunakg2005/qids-go) |
| **Java** | `com.github.Raunakg2005:qids-java:v1.3.4` (JitPack) | [qids-java](https://github.com/Raunakg2005/qids-java) |
| **C / C++** *(primitives)* | `make` → `libqids.a` | [qids-c](https://github.com/Raunakg2005/qids-c) |
| **Julia** *(primitives)* | `Pkg.add(url="https://github.com/Raunakg2005/QIDS.jl.git")` | [QIDS.jl](https://github.com/Raunakg2005/QIDS.jl) |

---

## Documentation & Support

- **Website**: [https://raunakg2005.github.io/qids-website/](https://raunakg2005.github.io/qids-website/)
- **API reference**: every gateway serves its own at `/docs`
- **Contact**: [raunakg2005@gmail.com](mailto:raunakg2005@gmail.com)
- **License**: Proprietary and Confidential. Copyright &copy; 2026 QIDS. All Rights Reserved. See [LICENSE](LICENSE) for terms.

