@variantlab/core 0.1.4 → 0.1.6

package/docs/research/origin-story.md

@@ -0,0 +1,179 @@
+# Origin story: the small-phone card problem
+
+variantlab exists because of a very specific real-world problem we failed to solve cleanly in another project: Drishtikon Mobile, a Bengali news aggregation app.
+
+## Table of contents
+
+- [The problem](#the-problem)
+- [What we tried](#what-we-tried)
+- [Why the ad-hoc solution doesn't scale](#why-the-ad-hoc-solution-doesnt-scale)
+- [The realization](#the-realization)
+- [Why this is generalizable](#why-this-is-generalizable)
+- [What we kept](#what-we-kept)
+
+---
+
+## The problem
+
+Drishtikon has a "detailed news card" component in a vertical feed. Each card shows:
+
+- A hero image (roughly 50% of the card height)
+- The article title (2 lines max)
+- A bias visualization bar (1 line, 24 px)
+- 3 claims (roughly 130 px)
+- 5 source avatars (roughly 90 px)
+- An action bar (44 px — bookmark, share, AI chat)
+
+On larger phones (iPhone 15 Pro, Pixel 8) the card fits comfortably. On smaller devices (iPhone SE, older Android) the card height shrinks to ~280-360 px and the content gets clipped or forces scrolling.
+
+The "obvious fix" — shrink the image — works up to a point, but on the smallest devices the image becomes uselessly tiny and the card still clips.
+
+We needed to test **many** layout strategies to pick the right one. We couldn't just ship one and hope. We had to put multiple side-by-side, try each on a real phone, and pick the best.
+
+---
+
+## What we tried
+
+We built a homebrew runtime mode switcher:
+
+```
+src/context/CardResizeModeContext.tsx  — React Context + AsyncStorage persistence
+src/components/ui/CardResizeModePicker.tsx  — floating button + bottom sheet picker
+src/components/feature/news-card/DetailedCardBody.tsx  — dispatcher with 30 mode components
+```
+
+Over several hours we iterated on this:
+
+1. First pass: 12 layout modes (responsive image, no-scroll, tap-collapse, drag-handle, bottom-sheet, parallax, title-overlay, accordion, horizontal, drag-snap, minimal, swipe-resize)
+2. "Think out of the box" pass: +6 modes (auto-fit, swipe-pages, adaptive-density, focus-peek, ambient-bias, sticky-parallax)
+3. "Impress me" pass: +6 modes (RSVP reader, 3D flip, liquid morph, radial wheel, breathing pulse, marquee ticker)
+4. "Those don't solve my issue" pass: +6 modes (scale-to-fit, fixed-ratio-tabs, measure-drop, text-first, pip-thumbnail, single-section carousel)
+
+Total: 30 modes switchable at runtime via a floating purple button.
+
+All 30 modes persist to AsyncStorage. The picker is route-scoped (only shows on the feed). The current mode is surfaced in the debug overlay as a number badge.
+
+**It works.** We can test every layout on every phone in the palm of our hand. The developer workflow is magical: change modes, feel the difference, pick a winner.
+
+---
+
+## Why the ad-hoc solution doesn't scale
+
+The problem is that everything we built is:
+
+1. **Hand-rolled** — every new experiment needs new boilerplate
+2. **Single-app** — the `CardResizeModeContext` only knows about card resize modes
+3. **Single-experiment** — we can't test card layout AND onboarding flow AND CTA copy at the same time
+4. **Not typed** — mode strings are stringly-typed throughout the app
+5. **Not persisted across reinstalls** — we lose our picks when wiping the app
+6. **Not shareable** — we can't send a QA team "try mode 27 on mode 15" in a message
+7. **Tied to the Drishtikon codebase** — the next app will have to build this again
+
+And crucially:
+
+> **The picker is better than any existing A/B testing tool we've used.** Firebase Remote Config has nothing like it. GrowthBook's dashboard is nice but doesn't let you try variants on a real device. LaunchDarkly's targeting UI is powerful but living in a browser tab instead of the app.
+
+The *experience* of opening a real phone, shaking it, and cycling through 30 UI variants with one tap — that is the killer feature no paid tool offers.
+
+---
+
+## The realization
+
+If this UX is so valuable, it shouldn't be locked to one app. It should be:
+
+1. **Generalized** — any experiment, any variant, any framework
+2. **Typed** — codegen'd IDs from a JSON config
+3. **Portable** — the same picker UX on Next.js, Remix, Vue, Svelte, React Native
+4. **Lightweight** — small enough to include in production builds without regret
+5. **Secure** — safe enough to ship remote config over the wire
+6. **Free** — because no one should pay $8.33/seat/month for what we just built in a weekend
+
+And so: **variantlab**.
+
+---
+
+## Why this is generalizable
+
+The Drishtikon problem was about layout. But every app has problems that benefit from the same workflow:
+
+- **Onboarding flow A/B tests**: "3-step vs 1-page"
+- **CTA copy tests**: "Buy now vs Get started vs Try free"
+- **Pricing tests**: "$9.99 vs $14.99"
+- **Color scheme tests**: "orange vs blue"
+- **Feature rollouts**: "new chat UI, 10% of users"
+- **Kill switches**: "disable the experimental AI tab if it crashes"
+- **Copy localization tests**: "formal vs casual Bengali"
+- **Layout experiments**: exactly Drishtikon's original problem
+
+Every single one of these is a variant experiment. Every single one benefits from:
+
+- A hand-switchable debug overlay on the device
+- Type-safe IDs so typos become compile errors
+- Route-aware filtering so the picker shows only what matters
+- Deep-link + QR override for QA
+- Crash-triggered rollback for safety
+
+Drishtikon forced us to invent the UX. variantlab is the refactor where we unlock it for everyone.
+
+---
+
+## What we kept
+
+Several design decisions in variantlab come directly from lessons learned building the ad-hoc solution:
+
+### 1. AsyncStorage-based persistence
+
+The ad-hoc version used AsyncStorage. variantlab ships AsyncStorage, MMKV, and SecureStore adapters out of the box, with `createMemoryStorage()` for tests.
+
+### 2. Floating debug button
+
+The Drishtikon picker has a floating purple button in the corner. variantlab ships the same pattern, configurable, tree-shakable, with shake-to-open as an opt-in.
+
+### 3. Route-scoped pickers
+
+Drishtikon's picker only appears on the feed route. variantlab generalizes this into the `routes` field on experiments and the `useRouteExperiments()` hook.
+
+### 4. Bottom-sheet modal with rich descriptions
+
+The Drishtikon picker bottom sheet shows the mode label + description. variantlab ships the same UX, plus search, favorites, and QR share.
+
+### 5. One component per variant
+
+Drishtikon's `DetailedCardBody.tsx` has a switch statement dispatching to 30 mode components. variantlab's `<Variant>` render-prop component is the generic version of this pattern.
+
+### 6. Developer-first ergonomics
+
+The Drishtikon picker is *fun* to use. It feels like Storybook for layouts. variantlab preserves that feel — the debug overlay is a first-class product, not an afterthought.
+
+---
+
+## The first migration
+
+The first real-world user of variantlab will be Drishtikon itself. We will:
+
+1. Replace `CardResizeModeContext` with `@variantlab/core` + `@variantlab/react-native`
+2. Replace `CardResizeModePicker` with `<VariantDebugOverlay>`
+3. Move the 30 mode definitions into `experiments.json`
+4. Replace the dispatcher switch with `<Variant experimentId="news-card-layout">`
+5. Delete ~2000 lines of hand-rolled code
+
+This migration is the single most valuable reality check for the variantlab API. If it doesn't feel cleaner than the ad-hoc version, the API is wrong and we iterate.
+
+---
+
+## Lessons that shaped the architecture
+
+1. **Runtime picker UX is the product.** Everything else — remote config, dashboards, analytics — is secondary.
+2. **Route-scoping is essential.** On a big app with many experiments, showing all of them at all times is overwhelming. Filter by current route.
+3. **Persistence must survive hot reload.** The developer's flow is "make a change, hot reload, re-check the mode". Lost state kills the flow.
+4. **Configs are documents, not databases.** Treat `experiments.json` like a README — versioned, reviewed, diffable.
+5. **Never break production by accident.** Crash-triggered rollback was born from shipping a card mode that crashed on certain article data. We want the safety net built in.
+6. **Frameworks are plural now.** A React-only solution is a dead end in 2026. We use Next.js, React Native, and Vite-React in the same organization. Every real team does.
+
+---
+
+## See also
+
+- [`README.md`](../../README.md) — the public pitch
+- [`ROADMAP.md`](../../ROADMAP.md) — the phased plan
+- [`docs/features/debug-overlay.md`](../features/debug-overlay.md) — the debug overlay design

package/docs/research/security-threats.md

@@ -0,0 +1,312 @@
+# Security threat research
+
+Extended research behind the threats and mitigations documented in [`SECURITY.md`](../../SECURITY.md). This file goes deeper into the reasoning, references, and historical incidents that inform each decision.
+
+## Table of contents
+
+- [Scope](#scope)
+- [Historical incidents we learned from](#historical-incidents-we-learned-from)
+- [Threat categories](#threat-categories)
+- [Deep-dives](#deep-dives)
+- [Open questions](#open-questions)
+- [References](#references)
+
+---
+
+## Scope
+
+variantlab is a client-side configuration and variant-resolution library. Its threat surface includes:
+
+1. **Config integrity** — can the config be tampered with in transit or at rest?
+2. **Code execution** — can a malicious config execute code?
+3. **Data exfiltration** — can variantlab leak user data?
+4. **Storage integrity** — can local storage be tampered with?
+5. **Supply chain** — can an upstream compromise affect downstream users?
+6. **Denial of service** — can a malicious config crash or exhaust the runtime?
+
+Out of scope (the user's responsibility):
+
+- Authentication of users (we don't do auth)
+- Securing the backend that serves the config
+- Encrypting user data at rest (handled by the user's backend)
+- Protecting secrets used to sign configs (key management is user-owned)
+
+---
+
+## Historical incidents we learned from
+
+### 1. The `event-stream` incident (2018)
+
+**What happened**: A maintainer handed control of a popular npm package (`event-stream`) to an anonymous contributor who added a malicious dependency targeting cryptocurrency wallets.
+
+**Lesson**: Every runtime dependency is a trust decision. Even seemingly benign packages can be compromised. Our response: zero runtime deps in `@variantlab/core`.
+
+**Reference**: https://github.com/dominictarr/event-stream/issues/116
+
+### 2. The `ua-parser-js` hijack (2021)
+
+**What happened**: A compromised maintainer account published a malicious version of `ua-parser-js`, a package with 7M+ weekly downloads.
+
+**Lesson**: Even with 2FA, account compromise is possible. Defense in depth via signed releases and provenance attestations.
+
+**Reference**: https://github.com/advisories/GHSA-pjwm-rvh2-c87w
+
+### 3. The `node-ipc` protestware incident (2022)
+
+**What happened**: A maintainer added code that wiped files on machines with specific geolocation.
+
+**Lesson**: Trust of maintainers cannot be absolute. Our response: reproducible builds so any divergence is detectable.
+
+**Reference**: https://github.com/advisories/GHSA-97m3-w2cp-4xx6
+
+### 4. The `xz-utils` backdoor (2024)
+
+**What happened**: A multi-year social engineering campaign introduced a backdoor into a popular upstream project via a seemingly legitimate contributor.
+
+**Lesson**: Review every contribution with paranoia. Multi-reviewer approval on sensitive changes. Reproducible builds.
+
+**Reference**: https://research.swtch.com/xz-timeline
+
+### 5. Prototype pollution in `lodash.merge` (2018-2020)
+
+**What happened**: Multiple CVEs against `lodash.merge` for prototype pollution via crafted input.
+
+**Lesson**: Don't deep-merge untrusted objects. Our response: no deep merge in config processing; whitelist-only object parsing.
+
+**Reference**: CVE-2019-10744, CVE-2020-8203
+
+### 6. Firebase Remote Config bypass (hypothetical, not a specific CVE)
+
+**What it illustrates**: Any client-controlled config can be tampered with by a sufficiently motivated user. The mitigation is to never trust config for security decisions.
+
+**Lesson**: Our docs must clearly warn users not to use feature flags for access control.
+
+---
+
+## Threat categories
+
+### A. Integrity threats
+
+Threats that allow an attacker to change what config the client sees.
+
+- **A1**: MITM on remote config endpoint
+- **A2**: Compromised CDN origin
+- **A3**: DNS hijack
+- **A4**: BGP hijack
+- **A5**: Compromised storage bucket
+- **A6**: Compromised npm package
+- **A7**: Compromised build pipeline
+- **A8**: Local storage tampering
+
+### B. Confidentiality threats
+
+Threats that leak user data or secrets.
+
+- **B1**: Telemetry leaking PII
+- **B2**: Analytics integration leaking variant assignments to third parties
+- **B3**: Debug overlay shown in production
+- **B4**: Error messages revealing experiment structure
+- **B5**: Timing attacks on HMAC verification
+- **B6**: Cache poisoning allowing observation of other users' states
+
+### C. Availability threats
+
+Threats that cause service degradation or denial of service.
+
+- **C1**: Oversized config
+- **C2**: Exponential regex / ReDoS
+- **C3**: Deeply nested targeting predicates
+- **C4**: Infinite polling loops
+- **C5**: Memory exhaustion via time-travel history
+- **C6**: Crash storm triggering rollback fatigue
+
+### D. Code execution threats
+
+Threats that achieve arbitrary code execution.
+
+- **D1**: Config containing `eval`-able payloads
+- **D2**: Prototype pollution leading to method hijacking
+- **D3**: Dynamic import of attacker-controlled URLs
+- **D4**: Regex with code execution side effects (does not exist in JS, but in case we ever bind to a native engine)
+
+### E. Misuse threats
+
+Threats that come from mis-configuration by the user.
+
+- **E1**: Using variantlab for authorization decisions
+- **E2**: Storing secrets in variant values
+- **E3**: Exposing debug overlay in production
+- **E4**: Forgetting to verify HMAC on remote configs
+- **E5**: Using a weak HMAC key
+
+---
+
+## Deep-dives
+
+### Deep-dive: prototype pollution
+
+JavaScript's prototype chain is a known attack vector. When parsing untrusted JSON:
+
+```js
+// UNSAFE
+const config = JSON.parse(untrustedInput);
+const merged = { ...defaults, ...config };
+// If untrustedInput contains `{"__proto__": {"admin": true}}`,
+// every object in the program now has `.admin === true`.
+```
+
+**Our mitigations**:
+
+1. **Never spread untrusted objects into others**. Use property-by-property allow-listing.
+2. **Use `Object.create(null)`** for all parsed data structures. These objects have no prototype.
+3. **Explicitly reject keys**: `__proto__`, `constructor`, `prototype`, `__defineGetter__`, `__defineSetter__`.
+4. **Freeze the config** after loading so accidental mutations throw in strict mode.
+
+Implementation sketch:
+
+```ts
+function safeParse(input: string): unknown {
+  const parsed = JSON.parse(input, (key, value) => {
+    if (
+      key === "__proto__" ||
+      key === "constructor" ||
+      key === "prototype"
+    ) {
+      return undefined; // strip it
+    }
+    return value;
+  });
+  return parsed;
+}
+```
+
+### Deep-dive: ReDoS (Regex Denial of Service)
+
+A crafted regex or input can cause catastrophic backtracking, consuming CPU indefinitely.
+
+**Our mitigations**:
+
+1. **Avoid regex in hot paths**. Route globs and semver matching use purpose-built parsers, not regex.
+2. **If we must use regex**, only use constant patterns defined by us, never user-supplied patterns.
+3. **Input length limits**: config size capped at 1 MB, individual strings capped at 256-512 bytes.
+4. **Linear-time matchers**: all targeting predicates are O(n) in input size.
+
+### Deep-dive: HMAC timing attacks
+
+Naive HMAC comparison:
+
+```ts
+// UNSAFE
+function verify(sig: Uint8Array, expected: Uint8Array): boolean {
+  for (let i = 0; i < expected.length; i++) {
+    if (sig[i] !== expected[i]) return false;
+  }
+  return true;
+}
+```
+
+This is timing-dependent. An attacker measuring verification time can guess the HMAC byte-by-byte.
+
+**Our mitigation**: Use `crypto.subtle.verify` exclusively. It is specified to be constant-time in conforming implementations of the Web Crypto API.
+
+```ts
+const valid = await crypto.subtle.verify("HMAC", key, signature, data);
+```
+
+We never implement HMAC comparison ourselves.
+
+### Deep-dive: CSP compatibility
+
+Content Security Policy is a browser feature that restricts what code can execute. The strictest policies reject:
+
+- Inline scripts (`'unsafe-inline'`)
+- `eval` and friends (`'unsafe-eval'`)
+- External scripts not from explicit origins
+- `data:` URIs in script-src
+
+**variantlab is CSP-strict compatible**:
+
+- Zero uses of `eval`, `Function()`, `setTimeout("string")`, `setInterval("string")`
+- Zero inline `<script>` injection
+- Debug overlay CSS is applied via inline styles only in dev mode (guarded by `__DEV__`)
+
+We test CSP compatibility via a Playwright test that loads an example app under `Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'`.
+
+### Deep-dive: supply chain attack surface
+
+Even with zero runtime dependencies, our supply chain includes:
+
+1. **Dev dependencies** (tsup, typescript, biome, etc.) used at build time
+2. **The build pipeline** (GitHub Actions runners, tools)
+3. **The publish pipeline** (npm registry, our tokens)
+4. **The end-user's install process** (lockfile, post-install scripts)
+
+**Our mitigations**:
+
+- **Pin dev dependencies to exact versions** in `pnpm-lock.yaml`
+- **Regular `pnpm audit`** in CI
+- **`socket.dev` checks** on every PR for known bad packages
+- **Sigstore signing** on every release
+- **npm provenance** attesting to the exact GitHub Actions workflow run
+- **Hardware-key-protected maintainer accounts**
+- **No post-install scripts** in any published package
+- **Reproducible build** documentation so anyone can verify tarballs
+
+### Deep-dive: debug overlay in production
+
+A developer copies `<VariantDebugOverlay />` into `app.tsx` for dev work, forgets to gate it, and ships it to production. End users can now toggle experiments.
+
+**Our mitigations**:
+
+1. **Tree-shake by default**. The overlay lives in a separate entry point (`@variantlab/react-native/debug`) that production builds can skip.
+2. **Runtime guard**. The overlay component checks `process.env.NODE_ENV !== "production"` and throws a loud error in prod unless an explicit `__forceDevOverlay` prop is set.
+3. **ESLint rule** (Phase 3) that warns when the overlay is imported without a `__DEV__` guard.
+4. **Documentation** — every example shows the guard.
+5. **Documentation alert** — a big warning banner on the overlay docs page.
+
+### Deep-dive: variantlab is not a security control
+
+Feature flags are often misused as access control. A flag `isAdmin: true` is trivially flippable by the user via local storage tampering or debug overlay.
+
+**Our docs must state prominently**:
+
+> **variantlab is not an authorization mechanism. Do not use feature flags to control access to sensitive data or operations. All security decisions must be enforced server-side.**
+
+We include this warning in:
+
+- `README.md`
+- `SECURITY.md`
+- `docs/features/killer-features.md`
+- The debug overlay itself (a small warning next to the pick buttons)
+
+---
+
+## Open questions
+
+1. **Should we ship a reference HMAC-signing Cloudflare Worker?** Yes — it demonstrates the pattern and gives users a working starting point. Target: Phase 4.
+2. **Should we support encryption at rest for local storage?** Debated. Most cases don't need it. We'll ship an `EncryptedStorageAdapter` as an optional entry point in Phase 4.
+3. **Should we have a bug bounty?** Not until post-v1.0. Until then, rely on responsible disclosure.
+4. **Should core run in a Web Worker?** Interesting but not required. Users can instantiate the engine in a worker themselves if desired.
+5. **Do we need a Content-Security-Policy reporting endpoint?** No — we don't process reports, users do.
+
+---
+
+## References
+
+- Web Crypto API: https://www.w3.org/TR/WebCryptoAPI/
+- OWASP Top 10 for LLMs: https://owasp.org/www-project-top-10-for-large-language-model-applications/
+- CSP Level 3: https://www.w3.org/TR/CSP3/
+- Sigstore: https://www.sigstore.dev/
+- npm Provenance: https://docs.npmjs.com/generating-provenance-statements
+- SLSA: https://slsa.dev/
+- CycloneDX SBOM: https://cyclonedx.org/
+- Prototype Pollution primer: https://github.com/BlackFan/client-side-prototype-pollution
+- ReDoS primer: https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
+
+---
+
+## See also
+
+- [`SECURITY.md`](../../SECURITY.md) — the canonical threat model and mitigations
+- [`docs/features/hmac-signing.md`](../features/hmac-signing.md) — HMAC signing implementation
+- [`docs/research/bundle-size-analysis.md`](./bundle-size-analysis.md) — why zero deps matters for security too

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/core",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The framework-agnostic variantlab engine. Zero dependencies, runs anywhere.",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "publishConfig": {