echokit

What is the EchoKit Worker and Why Do You Need It?

🎉 Your Worker is LIVE!

Worker URL: https://echokit-license.echokit-rk.workers.dev
Status: ✅ Deployed and healthy
Health Check: Working perfectly!
Secrets: ✅ HMAC_SECRET and ADMIN_TOKEN configured

🤔 What is it in Simple Terms?

The EchoKit Worker is a tiny app running in the cloud that checks if EchoKit Pro license keys are real and valid.

Think of it like a bouncer at a club - when someone shows a VIP pass (license key), the bouncer checks:

Is this pass real? (not fake)
Is it expired?
What level of VIP? (PRO/YEAR/LTD)

Where it runs: Cloudflare’s global network (200+ cities worldwide)
Cost: $0/month (free tier covers everything)
Speed: <10ms anywhere in the world

🎯 Why You NEED It

Scenario: You’re Selling EchoKit Pro

WITHOUT a Worker ❌:

Customer buys Pro → You manually email them a “license key” (just random text)
Customer enters key → Extension just checks “is it not empty?”
Problem: Customer shares key with 10 friends → All get Pro features
Result: You sell 1 license, 10 people use it = 90% revenue loss 💸

WITH a Worker ✅:

Customer buys Pro → Worker automatically generates a cryptographically signed key
Key looks like: EK-PRO-1738281600-a1b2c3d4e5f6 (has math proof built-in)
Customer enters key → Extension asks Worker: “Is this real?”
Worker checks signature (like verifying a signed document)
If friend tries to share: Each use is validated, you can detect patterns
Result: Secure revenue, prevent piracy ✅

🔐 How the Magic Works

License Key Anatomy

EK-PRO-1738281600-a1b2c3d4e5f6
│   │   │          │
│   │   │          └── Signature (mathematical proof it's real)
│   │   └───────────── Expiry date (Unix timestamp)
│   └───────────────── Plan type (PRO/YEAR/LTD)
└───────────────────── EchoKit prefix

The signature is created using HMAC-SHA256 cryptography with your secret key. Without knowing your secret, it’s mathematically impossible to create a valid signature. Even a supercomputer couldn’t crack it in billions of years.

Validation Flow (What Happens Behind the Scenes)

1. User pastes key in EchoKit extension
2. Extension sends to Worker: "Is EK-PRO-1738281600-a1b2c3d4e5f6 valid?"
3. Worker checks:
   ✓ Format correct? (EK-PLAN-TIMESTAMP-SIG)
   ✓ Signature matches? (uses your secret to verify)
   ✓ Not expired? (compares timestamp to now)
4. Worker responds: "✅ YES! Plan: PRO, Expires: Dec 31, 2026"
5. Extension unlocks Pro features

Security: Only YOU know the ECHOKIT_HMAC_SECRET. Nobody else can create valid keys.

🌐 What the Worker Can Do

1. Health Check (Is it alive?)

curl https://echokit-license.echokit-rk.workers.dev/__health
# Response: {"ok":true,"name":"EchoKit License API"}

2. Validate Keys (Extension uses this)

POST /v1/validate
Body: {"key": "EK-PRO-1738281600-..."}

# If valid:
{"valid": true, "plan": "PRO", "expiresAt": 1738281600}

# If fake:
{"valid": false, "error": "invalid signature"}

3. Issue New Keys (You use this to create keys)

POST /v1/issue
Headers: Authorization: Bearer <YOUR_ADMIN_TOKEN>
Body: {"plan": "PRO", "expiresAt": 0}

# Response:
{"ok": true, "key": "EK-PRO-1738281600-a1b2c3d4", "plan": "PRO"}

4. Payment Automation (Customer pays → Auto-issue key)

POST /v1/stripe-webhook        # Stripe (already coded!)
POST /v1/lemonsqueezy-webhook  # LemonSqueezy (recommended to add)

# When customer pays:
# → Webhook fires
# → Worker generates key
# → Email sent automatically

💰 Cost Breakdown

Cloudflare Workers Free Tier:

✅ 100,000 requests per day = FREE
✅ Global CDN (200+ cities)
✅ 99.99% uptime
✅ Unlimited CPU time

Your actual usage with 1,000 Pro users:

Each user validates license ~1x per day
Plus occasional re-validations
= ~30,000 requests/day
Cost: $0 (well under the free limit)

If you somehow exceed 100K/day: $5/month for 10 million requests.

Verdict: You’ll never pay for this. Free forever.

🎮 Real-World Customer Journey

Let’s say Sarah wants to buy EchoKit Lifetime:

Sarah clicks “Buy Lifetime” ($199) on your pricing page
Payment processor (Stripe/LemonSqueezy) charges her card
Webhook fires → Worker receives “payment successful” notification
Worker generates key: EK-LTD-0-f3a8b2c1 (LTD = lifetime, 0 = never expires)
Email sent automatically: “Thanks Sarah! Your license: EK-LTD-0-f3a8b2c1”
Sarah opens EchoKit → Settings → Pastes key
Extension asks Worker: “Is EK-LTD-0-f3a8b2c1 valid?”
Worker validates: ✓ Signature matches ✓ Plan is LTD ✓ No expiry
Worker responds: “✅ Valid! Lifetime plan.”
Pro features unlock instantly ✨

All of this happens in <1 second with zero manual work from you.

🔧 Test It Right Now

cd worker

# Set your credentials (you got these during deployment)
export ECHOKIT_WORKER_URL="https://echokit-license.echokit-rk.workers.dev"
export ECHOKIT_ADMIN_TOKEN="<paste-your-admin-token>"

# Run the interactive key issuer
./issue-license.sh

It will ask:

Select plan type:
  1) PRO   - Monthly (30 days)
  2) YEAR  - Annual (365 days)
  3) LTD   - Lifetime (never expires)

Enter choice [1-3]: 3

Choose 3 → You’ll get a real lifetime license key!
Then test it in the extension.

🚀 Next Steps for Production

Set Up Automated Payments

Option A: LemonSqueezy 🌍 (RECOMMENDED)

Why: Handles ALL tax/VAT worldwide (you don’t deal with it!)
Setup time: 15 minutes
Guide: ../../../worker/LEMONSQUEEZY_INTEGRATION.md
Best for: Global sales, indie developers

Option B: Stripe (Already coded!)

Why: More established, webhook already implemented
Setup time: 1-2 hours (tax is complex)
Guide: ../../../worker/PAYMENT_AUTOMATION_SETUP.md
Best for: US-only or if you have accountants

Option C: Both!

Run dual webhooks
LemonSqueezy for new customers (easier)
Stripe for existing customers (no disruption)

❓ Common Questions

Q: What if I don’t use the worker?
A: EchoKit works fine, but only Free tier. No way to safely sell Pro without it.

Q: Can someone hack/crack the keys?
A: No. HMAC-SHA256 is military-grade crypto. Without your secret, impossible to forge.

Q: What if Cloudflare goes down?
A: Extension caches validations for 24 hours. Plus Cloudflare has 99.99% uptime (better than AWS).

Q: What if I lose ECHOKIT_HMAC_SECRET?
A: All existing keys become invalid. You’d need to issue new keys to all customers. SAVE IT IN YOUR PASSWORD MANAGER!

Q: Can I see who’s using what keys?
A: Current version doesn’t log. Future version could add analytics (KV store).

Q: Can I revoke a key if someone cheats?
A: Not in current version (stateless design). V2 could add a revocation list.

📊 Bottom Line

What it is: Your license server in the cloud
Why you need it: Prevent piracy, secure revenue, automate sales
Cost: $0/month
Speed: <10ms globally
Security: Impossible to crack
Your URL: https://echokit-license.echokit-rk.workers.dev

Without it: You can’t safely sell Pro licenses (anyone can fake keys)
With it: Enterprise-grade license management for free

🎯 Your worker is deployed and ready!
Test it now: cd worker && ./issue-license.sh 🚀