Date: 2026-05-29
Pain statement:
Client-side web apps (PWAs, learning platforms, SaaS shells) ship all their
logic to the browser. Any developer can open DevTools, copy the source, and
redeploy the app under a different domain. Obfuscation alone takes under an
afternoon to reverse. No modular, flag-based, drop-in library exists that
combines multiple 2026 browser APIs into layered protection.
Frequency:
Per-project — every client-side app faces this at launch.
Who feels it:
Indie developers and small teams shipping PWAs, interactive learning tools,
browser-based SaaS products that can't afford server-side rendering migration.
Current workaround:
- Manual obfuscation (obfuscator.io) — reversible in minutes
- Hand-rolled domain checks — overlays that are trivially removed
- Accepting the risk and moving on
Root cause or symptom?:
Root cause: the browser must receive code to execute it. Symptom: easy copying.
The library doesn't eliminate the root cause but raises the cost of exploitation
to where most attackers give up.
Gate result: [x] Pass — pain is real, recurring per-project, and the workaround (manual obfuscation) is known to be insufficient.
How it eliminates the pain:
Combines cryptographic domain binding, non-extractable keys, devtools detection,
anti-debug timing, headless detection, and content encryption into one
drop-in script with zero app restructuring required.
What changes in the user's workflow:
Add one <script> tag before app code. Configure flags. Run CLI to encrypt
content files at build time. Done.
Explicitly out of scope:
- Server-side auth (different problem)
- DRM-grade protection (browser limitation — not solvable)
- Protection against authenticated users who are determined (unwinnable arms race)
Simpler 80% alternative considered:
Manual obfuscation + copyright notice. Already in place for the triggering project.
Why the simpler alternative is insufficient:
It stops zero developers. A motivated person deobfuscates in one tool call.
The library combines cryptographic binding (not just visual obscurity) with
active behavioral detection — qualitatively different from obfuscation.
Gate result: [x] Pass
| Tool | What it does | What it doesn’t do | Why choose webshield |
|---|---|---|---|
| obfuscator.io | String/control-flow obfuscation | No domain binding, no devtools detection, no content encryption | webshield adds cryptographic and behavioral layers |
| JavaScript Obfuscator (npm) | Same as above, build-time | Same gaps | Same |
| Jscrambler (commercial) | Advanced obfuscation + some domain lock | Expensive, SaaS, black box, no flag-based composability | webshield is open, composable, free |
| jsfuck / aaencode | Encoding tricks | Trivially reversible, no protection value | Not comparable |
Genuine gap:
No open-source, zero-dependency, flag-based library that combines:
SubtleCrypto domain binding + non-extractable IDB keys + SharedArrayBuffer
anti-debug + OPFS install binding + closed ShadowDOM + Proxy honeypots.
These APIs exist and are mature in 2026 but nobody has composed them into
a single protection library.
Type of gap: technical composition gap — the APIs exist, the combination doesn't.
Considered contributing to existing tool instead?
Jscrambler is closed-source SaaS. Obfuscator.io is obfuscation-only with no
behavioral or cryptographic layer. No suitable open project to contribute to.
Gate result: [x] Pass
Hardest technical problem:
Non-extractable CryptoKey lifecycle — deriving a domain-bound key via HKDF,
storing it as non-extractable in IndexedDB, and reliably retrieving it across
sessions without it being accessible to JS. The API exists but the edge cases
(IDB unavailable, private browsing, key rotation) need careful handling.
Prototyped / proven?: Partial — SubtleCrypto HKDF and non-extractable key
storage are well-documented and tested in isolation. The composition into a
unified domain-binding flow is not yet prototyped.
Known unknowns:
- SharedArrayBuffer availability (requires COOP/COEP headers — app must set these)
- OPFS in private browsing mode (may be session-scoped only)
- CSS Houdini Paint Worklet support across browsers (Chrome-only in some versions)
- Trusted Types requiring server-side CSP header cooperation
Generalization-breaking assumptions:
- App is served over HTTPS (SubtleCrypto requires secure context)
- Host controls response headers (for COOP/COEP, Trusted Types CSP)
- App does not already use Service Worker (SW module requires coordination)
Graceful degradation:
Each module checks API availability before activating. Missing API = module
skips gracefully, logs warning in debug mode, does not crash app.
Gate result: [x] Pass — hard parts identified and bounded. Known unknowns are header-dependent, manageable.
Step 1: npm install webshield OR copy webshield.min.js
Step 2: Add <script> tag, call WebShield.init({ domains, protections })
Step 3: Run npx webshield encrypt for content files (optional)
Step 4: App is protected — verify in wrong-domain test
Drop-off point: Step 3 (CLI for content encryption adds friction). Steps 1-2
deliver immediate value without it.
Minimum path to first value: Steps 1-2 only. Domain lock + devtools detection
work with zero build changes.
Upfront investment required: ~10 minutes for basic setup, ~30 min for full
content encryption pipeline.
Investment proportional to payoff?: Yes — 10 min for meaningful domain
binding is a reasonable ask.
Gate result: [x] Pass
V1 scope:
IN: core engine, domain-lock, devtools-detect, anti-debug, anti-headless,
anti-iframe, dom-tamper, decoy-traps, content-encryption CLI, violation
handler (shutdown/degrade/redirect), unit + integration + e2e tests.
OUT: worker-isolation (requires app restructure), houdini-core (Chrome-only),
server-handshake CF Worker template (Phase 6+).
Realistic hours for V1 (Phases 1-5): ~40-60 hours across sessions.
Known scope creep risks:
- Users will ask for React/Vue hooks (planned as use* API — already in scope)
- Users will ask for Node.js/SSR support (out of scope — browser-only)
- Users will ask for TypeScript types (add in Phase 8, not before)
Ongoing maintenance triggers:
- Browser API deprecations (unlikely for SubtleCrypto, IDB, OPFS)
- New headless detection vectors (Playwright/Puppeteer update evasion techniques)
- SharedArrayBuffer policy changes
Who maintains it: Ahmed / Techiediaries. Low bus factor risk for personal tool.
Cost of abandonment: Users keep the last working version. Protections degrade
as browsers evolve but don't break. Acceptable.
Gate result: [x] Pass
Specific target user:
Indie developers shipping client-side PWAs, interactive learning tools,
browser-based SaaS on tight budgets who can't do server-side rendering.
Specifically: people who've already tried obfuscator.io and found it insufficient.
Discovery path:
"javascript protection library 2026", "prevent copy client side app",
"domain lock javascript", "webshield js" after Techiediaries tutorial series
publishes. Tutorial series is the primary acquisition channel.
Repeat use trigger:
Used in every new client-side project. Config copied from project to project.
Star on GitHub as reference, not contribution.
Novel part: the composition (tool) + the tutorial series (concept explained).
Both have value. Publish both simultaneously.
Minimum publishable version: Phases 1-4 complete (core + detection modules).
Content encryption (Phase 5) is a bonus, not required for initial publish.
Gate result: [x] Pass — audience is specific, discovery path is clear (tutorial-driven), novel part is the tool + series together.
[x] Go
All seven gates passed. Build starts at Phase 1. The use* composable API is included in the architecture from Phase 1 as a parallel export to WebShield.init() — see plan for details.