1. The Four Decoupled Domain States
In naive QR implementations, systems use a single boolean `is_active = true`. This is an architectural failure. VaahanSafe enforces four completely decoupled states across all relational schemas:
A. Payment State
Authoritative confirmation of financial transaction (`PENDING`, `PAID`, `FAILED`, `REFUNDED`). Governed exclusively by server-verified Cashfree signed webhook signatures. A paid order does not imply physical delivery or active service.
B. QR Lifecycle State
Tracks the physical sticker hardware (`INVENTORY`, `DISTRIBUTED`, `ASSIGNED`, `ACTIVATED`, `REPLACED`, `RETIRED`). A physical decal exists in warehouse inventory long before any user purchases it.
C. Entitlement State
Authoritative service capabilities (`DIGITAL_QR_ACCESS`, `SAFETY_VIEW_ACTIVE`, `EMERGENCY_ROUTING`). Entitlements require satisfying both the acquisition gate (verified payment OR verified retail activation) and verified vehicle ownership.
D. Subscription State
Optional plan-backed functionality (`TIER_FREE`, `TIER_STANDARD`, `TIER_PREMIUM`). Decoupled so that renewing or lapsing a subscription never corrupts physical decal identity.
2. The Three-Identifier Security Boundary
Under the VaahanSafe security charter, three values must never be collapsed or derived from each other:
| Identifier | Format / Example | Storage Location | Public Exposure Rule |
|---|---|---|---|
| 1. Internal Database ID | `qr_9x2k41b08f` | Cloudflare D1 Primary Key | STRICTLY PRIVATE: Never returned to client DOM or URLs |
| 2. Public Opaque Identifier | Cryptographically random, non-sequential value | D1 unique indexed column | PUBLIC: Encoded into the physical resolver URL |
| 3. Activation Secret Proof | Separate private claim credential | Server-side one-way verification | PRIVATE: Never encoded in the QR or exposed by the resolver |
3. Cryptographic Retail Activation Flow
When a customer purchases a retail package from an authorized distributor or dealership, the physical decal is in an inert `DISTRIBUTED` state. Scanning the decal reveals only an unactivated registration portal. Service enablement requires satisfying an atomic, server-verified verification handshake:
- 01
Public ID Resolution
The user scans the QR code; the browser resolves `qr.vaahansafe.com/{publicId}`. The edge worker confirms the decal exists in inventory and is eligible for initial claiming.
- 02
Owner Authentication & Mobile Gate
The user must authenticate with a verified Indian mobile number (+91) via real MSG91 SMS OTP. Anonymous or guest activations are prohibited.
- 03
Concealed Secret Proof Verification
The user reveals the separate private proof and enters it in the official activation flow. The server verifies it securely and limits repeated attempts.
- 04
Atomic Vehicle Binding & Entitlement Grant
After proof and ownership checks, the server must atomically claim the QR, bind it to the authorized vehicle and grant only the services available for that vehicle.