🛡️ parcel-shield-js

Privacy-first parcel security for Node.js. / Node.js için gizlilik odaklı kargo güvenliği.

🌍 Read in English | 🇹🇷 Türkçe okumak için tıklayın

---

🌍 English Documentation

Encrypt the address on every shipping label, allow couriers to decrypt it completely offline, and give people who find your discarded boxes a beautiful "your data is destroyed" experience — all in just a few lines of code.

The plaintext address never reaches your server. It lives only inside the QR code, protected by asymmetric encryption. A stranger scanning the box from the trash sees a sleek privacy page. Your courier's handheld device decrypts it locally without needing an internet connection.

✨ Why is it awesome?

• 🔐 Asymmetric, Offline-First: ECIES (P-256) or RSA-3072 hybrid encryption. Couriers decrypt with a private key; no network required.
• 🙈 Server-Blind: Sensitive data lives in the URL #fragment. Browsers never send fragments to the server.
• 💅 Ready-to-use UI: Every scan renders an animated, standalone greeting page (breathing lock, green checkmark + confetti, SweetAlert-style popup) via app.use().
• 📡 Event-Driven: Bind shield.on('scanned_by_stranger', ...) and shield.on('delivered_and_destroyed', ...) directly to your webhooks.
• 🗑️ True "Right to be Forgotten": Once delivery happens, the token is revoked and data is destroyed.

⚡ Quick Start

npm install parcel-shield-js express

import { Shield } from 'parcel-shield-js';
import express from 'express';

const app = express();
const shield = Shield.init({ baseUrl: '[https://track.acme.com](https://track.acme.com)' });

// 1. Serve the out-of-the-box animated UI
app.use(shield.uiMiddleware());

// 2. Generate a secure label
const parcel = await shield.generateQR(
  { recipient: 'Ada Lovelace', address: 'Bahçe Sok. 12/4', note: 'Do not ring the bell' },
  { merchant: 'Acme Store', orderRef: '#10245' } 
);

// 👉 Print this on the shipping box:
console.log(parcel.qrDataUrl); // data:image/png;base64,...

🧬 How the Privacy Trick Works

1. generateQR() ──► seal(address)
2. QR encodes: https://track.acme.com/s/<token>#p=<sealed>
3. Consumer scans: Browser opens URL ──► server sees ONLY <token> (fragments aren't sent).
4. Courier scans: SDK reads <sealed> locally ──► decryptOffline() ──► plaintext address revealed!

---

🇹🇷 Türkçe Dokümantasyon

Node.js için gizliliğe öncelik veren kargo güvenliği. Her kargo etiketindeki açık adresi şifreleyin, kuryelerin internetsiz ortamlarda (asansör, kırsal bölge) şifreyi çözmesini sağlayın ve çöpteki kutunuzu bulan yabancılara şık bir "verileriniz imha edildi" sayfası sunun.

Açık adres asla sunucunuza ulaşmaz. Sadece QR kodunun içinde, asimetrik şifreleme ile korunarak bulunur. Kuryenizin el terminali, internet bağlantısına hiç ihtiyaç duymadan şifreyi kendi içinde çözer.

✨ Neden Harika?

• 🔐 Asimetrik ve Çevrimdışı (Offline): ECIES (P-256) veya RSA-3072 hibrit şifreleme. Kuryeler cihazlarındaki özel anahtarla şifreyi internetsiz çözer.
• 🙈 Sunucu Körü (Server-Blind): Hassas veriler URL'de #fragment (parça) olarak bulunur ve tarayıcılar bu kısmı asla sunucuya göndermez.
• 💅 Hazır Kullanıcı Arayüzü (UI): Tek bir app.use() ile tüketici tarafında animasyonlu (nefes alan kilit, yeşil tik + konfeti) şık bir gizlilik sayfası oluşturur.
• 📡 Olay Odaklı (Event-Driven): shield.on('scanned_by_stranger', ...) gibi event'lerle çöpteki kargo okutulduğunda anında bildirim atın.
• 🗑️ Gerçek "Unutulma Hakkı" (KVKK Uyumu): Teslimat gerçekleştiğinde token iptal edilir ve veriler kalıcı olarak yok edilir.

⚡ Hızlı Başlangıç

npm install parcel-shield-js express

1. Kodu Yazmadan Sunucuyu Başlatın (E-ticaret İçin): Tüm arka uç sistemini (REST API, UI, Webhook'lar) tek satırla ayağa kaldırın:

BASE_URL=[https://track.acme.com](https://track.acme.com) SHIELD_API_KEY=my_secret_key npx parcel-shield serve

2. Manuel Entegrasyon (Express/NestJS):

import { Shield } from 'parcel-shield-js';

const shield = Shield.init({ baseUrl: '[https://track.acme.com](https://track.acme.com)' });

// 🔑 Otomatik oluşturulan anahtarları kurye terminallerine yükleyin:
console.log(shield.keys.publicKey, shield.keys.privateKey);

// Hazır müşteri ekranlarını aktif et:
app.use(shield.uiMiddleware());

// Güvenli kargo etiketi oluştur:
const parcel = await shield.generateQR(
  { recipient: 'Ada Lovelace', address: 'Bahçe Sok. 12/4, Kadıköy', note: 'Zile basmayın' },
  { merchant: 'Acme Store', orderRef: '#10245', region: 'İstanbul' } 
);

// 👉 Bunu kargo poşetine yazdırın:
parcel.qrDataUrl; // data:image/png;base64,…  (<img> etiketine koyun)

📱 Çevrimdışı Kurye PWA (İnternetsiz Teslimat)

Kuryeler için hazırlanan PWA (Progressive Web App) terminali sayesinde, kurye bir kez giriş yaptığında Private Key cihazın localStorage'ına kaydedilir.

Asansörde veya internetin çekmediği yerlerde kurye QR'ı okuttuğunda: Courier Device (Offline): QR ──► WebCrypto API ──► Private Key ──► Açık Adres şemasıyla veri sunucuya hiç gitmeden doğrudan cihazda çözülür.

🖼️ İki Farklı Tüketici Ekranı

Çöpteki veya yoldaki QR kodu okutan normal bir telefon şu iki ekrandan birini görür (Kişisel veriler asla gösterilmez):

1. Taşıma Sırasında: Yanıp sönen bir kilit animasyonu ve "Bu kargo henüz teslim edilmedi, bilgiler güvenlik için gizlenmiştir." uyarısı.
2. Teslim Edildikten Sonra: Animasyonlu yeşil onay işareti, konfeti ve "Bu kargonun üzerindeki kişisel veriler, gizliliğinizi korumak amacıyla kalıcı olarak imha edilmiştir 🛡️" yazılı SweetAlert tarzı ekran.

---

📚 Desteklenen Platformlar

• Express, NestJS, Fastify
• Özelleştirilebilir Depolama (Memory, Redis, Postgres, MongoDB)
• Shopify & WooCommerce Webhook Entegrasyonları (Plug & Play)

Made with ❤️ for Privacy.