You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+148-1Lines changed: 148 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,8 +31,27 @@
31
31
32
32
---
33
33
34
+
<details>
35
+
<summary><strong>🔬 What makes this "quantum"? — A plain-language primer</strong></summary>
36
+
<br>
37
+
38
+
Classical computers store information as **bits** — each one is either 0 or 1, like a light switch that is either off or on. A quantum computer uses **qubits**, which exploit two phenomena from quantum mechanics:
39
+
40
+
-**Superposition** — a qubit can be 0 and 1 *simultaneously* until it is measured, much like a coin spinning in the air is neither heads nor tails until it lands.
41
+
-**Entanglement** — two qubits can be linked so that measuring one instantly determines the state of the other, regardless of the distance between them. Einstein famously called this "spooky action at a distance."
42
+
43
+
This project uses a **quantum simulator** (AWS Braket SV1) to run small quantum circuits and harvest the inherent randomness of quantum measurement. The result is a number that is fundamentally unpredictable — not just hard to predict, but *physically impossible* to predict before the measurement occurs. That number seeds a cryptographic signature unique to each event participant.
44
+
45
+
**Why does this matter for identity?** Traditional random-number generators on classical computers are *pseudo*-random — they follow a deterministic algorithm that could, in principle, be reverse-engineered. Quantum randomness has no such algorithm underneath it. Using it as the root of a signature means the identity token carries a provenance that classical systems cannot replicate.
46
+
47
+
</details>
48
+
49
+
---
50
+
34
51
## 🌐 Overview
35
52
53
+
> **In plain terms:** Think of this as a live digital bulletin board for an event. Attendees post photos and messages in a Telegram group chat; those posts instantly appear as colourful sticky notes on a shared web screen — each one stamped with a unique identity token that was generated by a quantum computer. No two tokens are alike, and the randomness behind each one is rooted in the laws of physics rather than software.
54
+
36
55
When a participant sends a photo or message **@mentioning the bot** in a configured Telegram group, the system:
37
56
38
57
1.**Validates** the webhook request and sanitizes all input
@@ -60,6 +79,8 @@ Each user's signature is computed **once** on their first message and reused the
60
79
61
80
## 🏗️ Architecture
62
81
82
+
> **In plain terms:** The system has three layers — a *front door* (CloudFront CDN) that the public sees, a *processing engine* (a containerised web server running on AWS) that handles logic, and a *data layer* (database + file storage + quantum computer) that stores and authenticates everything. Telegram acts as the input channel: it pushes new messages to the engine the moment they are sent.
<summary><strong>🔬 Why these architectural choices? — Concepts explained</strong></summary>
116
+
<br>
117
+
118
+
**CDN (Content Delivery Network — CloudFront)**
119
+
A CDN is a geographically distributed network of servers that caches and delivers content from the location closest to each user. Think of it as having a local post office in every city rather than one central warehouse: your letter (web page) arrives faster because it travels a shorter distance. CloudFront also acts as a security shield — it strips malicious headers and enforces HTTPS before any request reaches the application.
120
+
121
+
**Containers & ECS Fargate**
122
+
A container packages an application and all its dependencies into a single, portable unit — like a shipping container that can be loaded onto any vessel regardless of what is inside. ECS Fargate runs these containers on AWS without requiring you to manage the underlying servers. The system automatically adds more containers when traffic spikes (e.g., during a live event) and removes them when traffic drops, so you only pay for what you use.
123
+
124
+
**DynamoDB (NoSQL database)**
125
+
Traditional relational databases store data in rigid tables with fixed columns, like a spreadsheet. DynamoDB is a *NoSQL* database that stores flexible documents, making it well-suited for message data where each record may have different fields (some messages have photos, some do not). It scales automatically and charges per read/write operation rather than per server — ideal for bursty event traffic.
126
+
127
+
**Webhook vs. polling**
128
+
A *webhook* is a "push" model: Telegram calls your server the instant a new message arrives, like a doorbell. The alternative — *polling* — would mean your server repeatedly asks Telegram "any new messages?" every few seconds, like repeatedly checking your mailbox. The backend uses a webhook for receiving messages (efficient, near-instant) while the browser uses polling to refresh the wall display (simpler, sufficient for a 5-second update cadence).
Every unique sender receives a **quantum-authenticated identity** generated by the AWS Braket SV1 state-vector simulator:
217
+
> **In plain terms:** Every person who posts on the wall receives a unique "quantum fingerprint" — a short code that was generated using the genuine randomness of quantum physics. It is displayed as a badge on their sticky note (`Q#452 | 7B284BB3D413`) and serves as a tamper-evident identity token for the duration of the event.
218
+
219
+
### How it works — step by step
179
220
180
221
```
181
222
Step 1 — 4-qubit Random Number Circuit
@@ -195,10 +236,61 @@ Step 4 — Visual Color
195
236
→ unique per-user card border color
196
237
```
197
238
239
+
<details>
240
+
<summary><strong>🔬 Unpacking the science — intuition for each step</strong></summary>
241
+
<br>
242
+
243
+
**Step 1 — Quantum Random Number Generation (4-qubit circuit)**
244
+
245
+
A classical computer generates "random" numbers using a mathematical formula seeded by something like the current time. Given the same seed, it always produces the same sequence — it is *deterministic*. A quantum circuit is different.
246
+
247
+
The circuit places four qubits into **superposition** using Hadamard (H) gates — each qubit is simultaneously 0 and 1. CNOT gates then **entangle** the qubits, linking their fates together. Finally, the circuit is measured 100 times ("100 shots"). Each measurement collapses the superposition and produces a random bitstring (e.g., `0110`, `1001`, `1101`…). The most frequently observed bitstring is converted to an integer — the *quantum number*.
248
+
249
+
The key insight: the outcome of each measurement is not determined by any prior state of the universe. It is genuinely random, in the same sense that radioactive decay is random. No algorithm, no matter how powerful, could have predicted it.
250
+
251
+
**Step 2 — Bell State Measurement (2-qubit circuit)**
252
+
253
+
A Bell state is one of the simplest and most famous examples of quantum entanglement. The circuit creates the state |Φ+⟩ = (|00⟩ + |11⟩) / √2 — meaning the two qubits are perfectly correlated: when measured, they are *always* both 0 or both 1, never mixed. Measuring this 200 times produces a probability distribution across the four possible outcomes (|00⟩, |01⟩, |10⟩, |11⟩).
254
+
255
+
In an ideal simulator, you expect roughly 50% |00⟩ and 50% |11⟩. The small deviations from perfect 50/50 — caused by the seed-based rotations applied in Step 1 — are unique to each user's input and contribute additional entropy to the signature.
256
+
257
+
**Step 3 — ToyLWE Signature**
258
+
259
+
LWE stands for **Learning With Errors**, a mathematical problem that is believed to be hard even for quantum computers to solve — making it a candidate for *post-quantum cryptography*. The "Toy" prefix signals that this implementation is a simplified, illustrative version rather than a production-hardened cryptographic primitive.
260
+
261
+
The quantum number from Step 1 is mixed with the user's name and random bytes using SHAKE-256 (a cryptographic hash function) to produce a *public key hash* — a short, shareable fingerprint. A second hash chain produces the *signature* itself. Together they form a pair: the signature can be verified against the public key hash, but the public key hash cannot be reversed to recover the original inputs.
262
+
263
+
**Step 4 — Visual Color from Quantum Data**
264
+
265
+
The quantum number and Bell state probabilities are mapped to an HSL (Hue, Saturation, Lightness) colour value. HSL is a perceptually intuitive colour model: hue is the "colour wheel" position (0°–360°), saturation is how vivid the colour is, and lightness is how bright it is. Because the quantum number spans 0–1000 and the Bell probabilities add continuous variation, each user's colour is visually distinct — you can literally *see* the quantum identity on the wall.
266
+
267
+
</details>
268
+
198
269
**Displayed on each card as:**`Q#452 | 7B284BB3D413`
199
270
200
271
> Signature is computed **once per sender per group** and reused on all subsequent messages. If Braket is unavailable, the system falls back to a local crypto-seeded equivalent — the wall never blocks.
201
272
273
+
### Quantum Circuit Diagrams
274
+
275
+
**Circuit A — 4-qubit Random Number Generator**
276
+
```
277
+
q[0]: ─ H ─ ● ─────────── Ry(θ₀) ─ M
278
+
q[1]: ─ H ─ ⊕ ─ ● ─────── Ry(θ₁) ─ M
279
+
q[2]: ─ H ─────── ⊕ ─ ● ─ Ry(θ₂) ─ M
280
+
q[3]: ─ H ─────────── ⊕ ─ Ry(θ₃) ─ M
281
+
282
+
θᵢ = π × (charCode(username[i]) mod 128) / 128
283
+
Shots: 100 → most frequent bitstring → quantumNumber
> **In plain terms:** The system is designed so that even if an attacker intercepts network traffic, gains access to the server's environment variables, or finds the public URL of the load balancer, they still cannot read messages, forge requests, or access photos. Every sensitive credential lives in a dedicated secrets vault, and every layer of the stack validates that requests come from a legitimate source before acting on them.
425
+
426
+
<details>
427
+
<summary><strong>🔬 Security concepts explained for non-specialists</strong></summary>
428
+
<br>
429
+
430
+
**Why "secrets in Secrets Manager" matters**
431
+
Developers often accidentally commit API keys or passwords directly into source code, where they become visible to anyone with repository access — and to automated scanners that continuously harvest leaked credentials from public repos. AWS Secrets Manager is a dedicated vault: the application retrieves credentials at runtime using an IAM role, so the actual values never appear in code, configuration files, or container images.
432
+
433
+
**What is TLS / HTTPS?**
434
+
TLS (Transport Layer Security) is the protocol that encrypts data in transit between your browser and a server. The padlock icon in your browser's address bar indicates TLS is active. Without it, anyone on the same network (e.g., a coffee-shop Wi-Fi) could read the data flowing between you and the site. HSTS (HTTP Strict Transport Security) is an additional instruction that tells browsers to *always* use HTTPS for this domain, even if a user types `http://` — preventing downgrade attacks.
435
+
436
+
**What is XSS (Cross-Site Scripting)?**
437
+
If a web application displays user-submitted text without sanitizing it, an attacker can submit text that contains JavaScript code. When other users view the page, their browsers execute that code — potentially stealing session tokens or redirecting them to malicious sites. This system encodes all user input as HTML entities (e.g., `<` becomes `<`) before storing or displaying it, so injected code is rendered as harmless text.
438
+
439
+
**What is least-privilege IAM?**
440
+
IAM (Identity and Access Management) controls what AWS resources each component is allowed to access. "Least privilege" means each component is granted only the minimum permissions it needs — the web server can read from DynamoDB and S3, but cannot, for example, delete IAM roles or access other AWS accounts. This limits the blast radius if any component is compromised.
441
+
442
+
</details>
443
+
332
444
| Layer | Mechanism |
333
445
|---|---|
334
446
|**Secrets**| All tokens and passwords in AWS Secrets Manager — never in code or env files |
@@ -421,6 +533,23 @@ ngrok http 3000
421
533
422
534
## 🔌 API Reference
423
535
536
+
> **In plain terms:** An API (Application Programming Interface) is a set of defined "doors" through which different software components talk to each other. Each row in the table below is one such door — it has an address (the endpoint), a method (what kind of action: read, write, delete), and an access rule (who is allowed to knock). Telegram uses the webhook door to push new messages in; browsers use the messages door to pull the wall display; the admin uses the admin doors to moderate content.
537
+
538
+
<details>
539
+
<summary><strong>🔬 REST and HTTP methods — a quick primer</strong></summary>
540
+
<br>
541
+
542
+
The web uses HTTP as its communication protocol. HTTP defines several *methods* that describe the intent of a request:
543
+
544
+
-**GET** — retrieve information without changing anything (like reading a notice board)
545
+
-**POST** — submit new data to be processed (like posting a letter)
546
+
-**PATCH** — partially update an existing record (like correcting one field on a form)
547
+
-**DELETE** — remove or hide a record
548
+
549
+
REST (Representational State Transfer) is a convention for organising these methods around *resources* — in this case, messages, groups, and admin actions. A RESTful API is predictable: if you know the resource name and the method, you can infer what the endpoint does.
> **In plain terms:** The system runs on a minimum of one server at all times (so it is always ready to receive Telegram messages) and can automatically spin up to four servers within 30 seconds if a large crowd starts posting simultaneously. When the rush subsides, extra servers are shut down after 60 seconds to avoid unnecessary cost. This elastic behaviour is a core advantage of cloud-native infrastructure — capacity follows demand rather than being fixed at the peak.
572
+
442
573
| Parameter | Value | Rationale |
443
574
|---|---|---|
444
575
| Min instances | 1 | Always-on for webhook reception |
@@ -451,6 +582,22 @@ ngrok http 3000
451
582
452
583
---
453
584
585
+
## 🌍 Interdisciplinary Context
586
+
587
+
This project sits at the intersection of three fields that rarely appear together in a single deployable system:
588
+
589
+
| Field | Contribution to this project |
590
+
|---|---|
591
+
|**Quantum computing**| Provides physically irreducible randomness as the root of identity tokens — a property no classical algorithm can replicate |
592
+
|**Cryptography**| Transforms raw quantum randomness into a structured, verifiable signature using hash functions and a post-quantum-inspired scheme (ToyLWE) |
593
+
|**Distributed systems / cloud engineering**| Delivers the result reliably at event scale — handling concurrent users, graceful degradation, and data persistence across a globally distributed infrastructure |
594
+
595
+
**Why combine them?** Each field compensates for the others' limitations. Quantum computing alone produces randomness but not structure. Cryptography provides structure but depends on the quality of its random inputs. Cloud infrastructure provides scale and reliability but has no inherent mechanism for generating unforgeable identity tokens. Together, they produce something none could achieve alone: a live, scalable, quantum-authenticated social display.
596
+
597
+
**On the "ToyLWE" label:** LWE (Learning With Errors) is a lattice-based cryptographic problem that underpins several NIST post-quantum cryptography standards (e.g., CRYSTALS-Kyber, CRYSTALS-Dilithium). The "Toy" implementation here is intentionally simplified for demonstration — it captures the structural intuition of LWE (mixing a secret with noise) without the full parameter hardening required for production security. It is best understood as a pedagogical bridge between quantum randomness and post-quantum cryptographic concepts.
0 commit comments