@variantlab/core 0.1.4 → 0.1.6

package/docs/features/debug-overlay.md

@@ -0,0 +1,328 @@
+# Debug overlay
+
+The on-device debug overlay is variantlab's signature feature. This document describes the design, the UX, and the security constraints.
+
+## Table of contents
+
+- [What it is](#what-it-is)
+- [UX design](#ux-design)
+- [Production safety](#production-safety)
+- [Activation modes](#activation-modes)
+- [Information architecture](#information-architecture)
+- [Customization](#customization)
+- [Accessibility](#accessibility)
+
+---
+
+## What it is
+
+`<VariantDebugOverlay>` is a component that renders a floating button plus a bottom-sheet picker. In dev builds, you mount it once at the root:
+
+```tsx
+import { VariantDebugOverlay } from "@variantlab/react-native";
+
+export default function App() {
+  return (
+    <VariantLabProvider>
+      <MainApp />
+      {__DEV__ && <VariantDebugOverlay />}
+    </VariantLabProvider>
+  );
+}
+```
+
+When the user taps the floating button (or shakes the device, if enabled), a bottom sheet slides up showing every experiment active on the current route.
+
+---
+
+## UX design
+
+### Floating button
+
+- 48×48 circle, absolute positioned
+- Configurable corner: `top-left`, `top-right`, `bottom-left`, `bottom-right`
+- Configurable offset from edges
+- Shows a badge with the count of active experiments on the current route
+- Long-press reveals a tooltip: "variantlab debug overlay"
+- Respects safe-area insets
+
+### Bottom sheet picker
+
+- Slides up from the bottom on tap
+- Dims the background (tap to dismiss)
+- Max height: 85% of screen
+- Contains:
+  1. A header bar with title + close button
+  2. A search input (filters by experiment name/ID)
+  3. A toggle: "Current route only" / "All experiments"
+  4. A scrollable list of experiment cards
+  5. A footer with "Reset all" and "Share state" buttons
+
+### Experiment card
+
+Each experiment card shows:
+
+- Experiment name
+- Experiment ID (subtle, monospace)
+- Current variant (highlighted)
+- Assignment reason ("by targeting", "by manual override", "by default")
+- Tap to expand: list of all variants with a radio picker
+- Each variant row shows: label, description, "set active" button
+- An overflow menu: "Copy ID", "Reset to default", "Share state"
+
+### Search
+
+- Case-insensitive, substring match on ID + name + label
+- Debounced 100 ms
+- Highlights matches in the list
+
+### Empty state
+
+When no experiments match the current route:
+
+> No experiments on this route.
+> Toggle "All experiments" above to see the full list.
+
+---
+
+## Production safety
+
+The overlay is a dev-only tool. In production, mounting it is a bug. We make it hard to do accidentally.
+
+### Auto-disable in production
+
+The overlay component checks multiple signals before rendering:
+
+```tsx
+function VariantDebugOverlay({ forceEnable = false }) {
+  const isDev =
+    forceEnable ||
+    (typeof __DEV__ !== "undefined" && __DEV__) ||
+    process.env.NODE_ENV === "development";
+
+  if (!isDev) {
+    if (process.env.NODE_ENV === "production") {
+      console.warn(
+        "[variantlab] VariantDebugOverlay rendered in production. " +
+          "Use forceEnable={true} if this is intentional.",
+      );
+    }
+    return null;
+  }
+
+  return <OverlayImpl />;
+}
+```
+
+### Tree-shaking in production builds
+
+The overlay implementation is exported from a separate entry point:
+
+```ts
+// @variantlab/react-native/debug
+export { VariantDebugOverlay } from "./overlay.js";
+```
+
+If the user doesn't import from `/debug`, the overlay code is not bundled. This keeps production bundles clean even if a developer forgets to wrap in `__DEV__`.
+
+### Never log user data
+
+The overlay uses the same storage as the engine and respects the same privacy rules:
+
+- No telemetry
+- No remote logging
+- No external network calls
+- All state is local
+
+### Rate-limited actions
+
+Rapid-fire variant switching is rate-limited to 5 changes/second to prevent accidental state thrashing or runaway loops.
+
+---
+
+## Activation modes
+
+### Tap (default)
+
+Tap the floating button to open.
+
+### Shake gesture (opt-in)
+
+```tsx
+<VariantDebugOverlay
+  activation={{ shake: true, shakeThreshold: 15 }}
+/>
+```
+
+Uses device motion to detect a shake. Threshold configurable. On React Native, uses `react-native`'s `DeviceEventEmitter` (Android) or a lightweight motion sensor abstraction. On web, uses `DeviceMotionEvent` (requires user permission on iOS).
+
+### Secret gesture
+
+Advanced: a 4-corner tap sequence in a specific order. Useful for hiding the overlay until QA knows the gesture.
+
+### Keyboard shortcut (web only)
+
+`Ctrl+Shift+V` toggles the overlay on web builds.
+
+### URL parameter (web only)
+
+Append `?__variantlab=1` to the URL to force-enable the overlay even in production (requires `forceEnable` on the component).
+
+---
+
+## Information architecture
+
+### The "Overview" tab (default)
+
+Shows experiments matching the current route, grouped by:
+
+- **Active** — experiments this user is enrolled in
+- **Targeted but not enrolled** — experiments the user matches but was excluded by weights
+- **Not targeted** — experiments that exist but don't match this user's context
+
+### The "History" tab
+
+Time-travel inspector. See [`time-travel.md`](./time-travel.md).
+
+### The "Context" tab
+
+Shows the current `VariantContext`:
+
+- Platform, app version, locale
+- Screen size bucket
+- Route
+- User ID (masked)
+- Attributes (JSON tree view)
+
+### The "Config" tab
+
+Shows the loaded config:
+
+- Version
+- Source (bundled / remote / file)
+- Last fetched
+- Signature status (valid / invalid / none)
+- Total experiments count
+
+### The "Events" tab
+
+Live-tailing telemetry stream (if configured):
+
+- Every `assignment`, `exposure`, `variantChanged`, `rollback` event
+- Timestamp, experiment, variant, reason
+- Can be paused and exported as JSON
+
+---
+
+## Customization
+
+Users can customize the overlay extensively:
+
+```tsx
+<VariantDebugOverlay
+  position="bottom-right"
+  offset={{ x: 20, y: 80 }}
+  theme="dark"
+  activation={{ tap: true, shake: true, shortcut: "mod+shift+v" }}
+  tabs={["overview", "history", "context", "config", "events"]}
+  showBadge
+  locked={false}
+  onOpen={() => console.log("overlay opened")}
+  onClose={() => console.log("overlay closed")}
+  onVariantChange={(exp, variant) => console.log(exp, variant)}
+  renderButton={(props) => <CustomButton {...props} />}
+/>
+```
+
+### Custom button render
+
+Users who want a non-floating button can render their own trigger:
+
+```tsx
+<VariantDebugOverlay renderButton={() => null} ref={overlayRef} />
+
+<Button onPress={() => overlayRef.current?.open()}>
+  Open debug
+</Button>
+```
+
+### Custom theme
+
+The overlay respects the app's dark/light theme by default, but users can override:
+
+```tsx
+<VariantDebugOverlay
+  theme={{
+    background: "#1a1a1a",
+    foreground: "#ffffff",
+    accent: "#8b5cf6",
+    border: "#333",
+  }}
+/>
+```
+
+---
+
+## Accessibility
+
+### Screen readers
+
+- The floating button has `accessibilityLabel="Open variantlab debug overlay"`
+- Each experiment card announces: "Experiment {name}, current variant {variant}, double tap to expand"
+- Variant radios use native radio semantics
+- Focus is trapped inside the sheet when open
+- ESC closes the sheet (web)
+
+### Keyboard navigation (web)
+
+- `Tab` cycles focus through controls
+- `Enter` / `Space` activates buttons
+- Arrow keys move between variant rows
+- `ESC` closes the overlay
+
+### Reduced motion
+
+If the user has `prefers-reduced-motion`, the slide animation is replaced with a fade.
+
+### Contrast
+
+All text meets WCAG AA contrast against the overlay background in both light and dark themes.
+
+---
+
+## Performance
+
+- The overlay lazy-loads its tab implementations
+- The experiment list is virtualized when > 50 experiments
+- The search input is debounced
+- No re-renders on unrelated state changes (isolated subscription)
+
+---
+
+## Dependencies
+
+- Core: `@variantlab/core`
+- React Native: no extra deps beyond React Native itself
+- Web: no extra deps beyond React
+- No animation library (hand-rolled with Animated API / CSS transitions)
+- No bottom-sheet library (hand-rolled modal)
+- No icon library (inline SVGs)
+
+This keeps the overlay < 4 KB gzipped even with all features.
+
+---
+
+## Integration with other features
+
+- **Route scoping** ([`targeting.md`](./targeting.md#routes)): the overlay filters by `useRouteExperiments`
+- **Time travel** ([`time-travel.md`](./time-travel.md)): the history tab
+- **QR sharing** ([`qr-sharing.md`](./qr-sharing.md)): the "Share state" button generates a QR
+- **Crash rollback** ([`crash-rollback.md`](./crash-rollback.md)): rollback events show in the events tab
+- **Codegen** ([`codegen.md`](./codegen.md)): overlay shows variant labels from the generated types
+
+---
+
+## See also
+
+- [`API.md`](../../API.md) — `VariantDebugOverlay` props
+- [`origin-story.md`](../research/origin-story.md) — why this feature exists

package/docs/features/hmac-signing.md

@@ -0,0 +1,330 @@
+# HMAC-signed remote configs
+
+Tamper-proof remote config delivery via HMAC-SHA256 signatures verified with Web Crypto API.
+
+## Table of contents
+
+- [Why signing matters](#why-signing-matters)
+- [The threat model](#the-threat-model)
+- [How it works](#how-it-works)
+- [Generating a signature](#generating-a-signature)
+- [Verifying a signature](#verifying-a-signature)
+- [Key management](#key-management)
+- [What signing does NOT protect](#what-signing-does-not-protect)
+- [Deployment workflow](#deployment-workflow)
+
+---
+
+## Why signing matters
+
+When your app fetches `experiments.json` from a remote URL, anyone who can intercept that request can modify the config. That includes:
+
+- MITM attackers on public Wi-Fi
+- Compromised CDNs
+- DNS hijacking
+- Rogue employees with deploy access
+- Supply chain attackers in your build pipeline
+
+A modified config can:
+
+- Enable features meant for staging
+- Change pricing
+- Collect user data (if combined with telemetry)
+- Break the app via invalid variants
+
+TLS is **not sufficient**. TLS protects the transport, not the content. If the attacker compromises your CDN or your S3 bucket, they ship the config over TLS just like you do.
+
+HMAC signing protects the **content** regardless of how it was transported.
+
+---
+
+## The threat model
+
+variantlab signing defends against:
+
+- **T1**: Malicious remote config (CDN compromise, MITM, internal rogue) — mitigated by signing
+- **T2**: Tampered local storage (malicious app, device compromise) — out of scope (TLS + signing both fail)
+- **T8**: Unauthorized variant overrides via deep link — mitigated via the same HMAC mechanism on share payloads
+
+See [`SECURITY.md`](../../SECURITY.md) for the full threat table.
+
+---
+
+## How it works
+
+### Signing
+
+1. Developer writes `experiments.json`
+2. `variantlab sign experiments.json --key $SECRET` computes HMAC-SHA256 over the canonical JSON form
+3. The CLI writes the signature into the `signature` field of the JSON
+4. The signed file is deployed to the CDN
+
+### Verification
+
+1. App fetches the signed JSON
+2. Engine extracts the `signature` field and strips it from the JSON
+3. Engine computes HMAC-SHA256 over the canonical form of the remaining JSON
+4. Engine compares the computed signature with the provided signature using `crypto.subtle.verify` (constant time)
+5. If they match, the config is applied. If not, the config is rejected and the engine falls back to the bundled config.
+
+### Canonical form
+
+HMAC requires a deterministic byte representation of the input. We define the canonical form as:
+
+- UTF-8 encoding
+- Keys sorted lexicographically at every level
+- No whitespace
+- `"\u"` escapes normalized
+- Signature field removed before signing/verifying
+
+This matches [RFC 8785 (JSON Canonicalization Scheme)](https://www.rfc-editor.org/rfc/rfc8785).
+
+---
+
+## Generating a signature
+
+### CLI
+
+```bash
+# Set the key via env var
+export VARIANTLAB_HMAC_KEY=mysecret123
+
+# Sign the file in place
+variantlab sign experiments.json
+
+# Or pipe
+cat experiments.json | variantlab sign --key $VARIANTLAB_HMAC_KEY > signed.json
+```
+
+### Programmatically
+
+```ts
+import { signConfig } from "@variantlab/cli";
+
+const signed = await signConfig(config, {
+  key: process.env.VARIANTLAB_HMAC_KEY,
+});
+// signed.signature = "base64url-encoded-signature"
+```
+
+### Output format
+
+```json
+{
+  "$schema": "https://variantlab.dev/schemas/experiments.schema.json",
+  "version": 1,
+  "signature": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
+  "experiments": [...]
+}
+```
+
+The signature is the base64url-encoded HMAC-SHA256 of the canonical form (with `signature` field excluded).
+
+---
+
+## Verifying a signature
+
+### At engine creation
+
+```ts
+import { createEngine } from "@variantlab/core";
+
+const engine = createEngine(config, {
+  hmacKey: process.env.NEXT_PUBLIC_VARIANTLAB_KEY,
+  onSignatureFailure: "reject", // or "warn"
+});
+```
+
+- `"reject"` — reject the config, fall back to the bundled one, emit a warning
+- `"warn"` — log a warning but still apply the config (useful for soft rollouts of signing)
+
+### With remote fetching
+
+```ts
+import { createHttpFetcher } from "@variantlab/core/fetcher";
+
+const fetcher = createHttpFetcher({
+  url: "https://cdn.example.com/experiments.json",
+  headers: { "Cache-Control": "no-cache" },
+});
+
+const engine = createEngine(initialConfig, {
+  fetcher,
+  hmacKey: "mysecret",
+  pollInterval: 60000,
+});
+```
+
+Every fetched config is verified before being applied.
+
+### Manual verification
+
+```ts
+import { verifySignature } from "@variantlab/core/crypto";
+
+const isValid = await verifySignature(config, key);
+if (!isValid) {
+  throw new Error("Config signature invalid");
+}
+```
+
+---
+
+## Key management
+
+The HMAC key is a shared secret between:
+
+1. The build system that signs configs
+2. The client app that verifies them
+
+### Where to store the key
+
+**On the build system**:
+
+- Environment variable in CI (`VARIANTLAB_HMAC_KEY`)
+- Secrets manager (AWS Secrets Manager, Vault, GCP Secret Manager)
+- **Never** commit to git
+
+**On the client**:
+
+- Embedded at build time via env var (`NEXT_PUBLIC_VARIANTLAB_KEY`)
+- The key is visible in the client bundle — treat it as a shared secret, not a private key
+- **This means**: anyone who reverse-engineers your app can extract the key
+
+### Why is that OK?
+
+HMAC is not authenticating the user; it's authenticating the **config source**. Even if an attacker extracts the key, they still can't:
+
+- Push a signed config to your CDN (they'd need deploy access)
+- Forge a config that your CDN serves (it's the CDN's bytes, not theirs)
+
+The only attack the extracted key enables is: the attacker signs their own config and somehow gets your app to fetch it (e.g., via a malicious deep link with a custom fetcher). That's a multi-step attack that signing alone can't prevent.
+
+### If you need key secrecy
+
+If you absolutely need the key to be secret:
+
+- Fetch the config from your authenticated API instead of a public CDN
+- Use TLS pinning in the fetcher
+- Sign with a rotating key that's fetched from a secure endpoint
+
+This is out of scope for variantlab core. We provide the primitives; you compose the policy.
+
+### Key rotation
+
+To rotate:
+
+1. Generate a new key
+2. Update the build system to sign with the new key
+3. Ship an app update with the new key
+4. Wait for the old app version to age out
+5. Retire the old key
+
+The engine supports **multiple keys** for smooth rotation:
+
+```ts
+createEngine(config, {
+  hmacKeys: [
+    { id: "v2", key: currentKey },
+    { id: "v1", key: previousKey },
+  ],
+});
+```
+
+The config's `signature` field can optionally include a key ID prefix: `"v2:dBjftJeZ..."`. The engine looks up the matching key.
+
+---
+
+## What signing does NOT protect
+
+### Replay attacks
+
+An old signed config is still valid. An attacker who captures `experiments.v1.json` can replay it later even after you've shipped `experiments.v2.json`.
+
+**Mitigation**: include a `nonce` or `timestamp` field in the config and reject old ones in the engine options. Post-v0.1.
+
+### Rollback to an older version
+
+Related to replay. If the attacker serves an older signed config with a lower `version`, the engine may accept it.
+
+**Mitigation**: the engine tracks the highest version it has seen and rejects configs with lower versions.
+
+### Key compromise
+
+If the HMAC key leaks, the attacker can sign arbitrary configs. Rotate the key immediately.
+
+### Bundled config tampering
+
+The bundled `experiments.json` (shipped inside the app binary) is not signed at runtime — if someone tampers with the app bundle, they can replace it. This is out of scope — if an attacker can modify your app binary, they can do far worse than change experiments.
+
+### DoS via malformed signature
+
+A config with an invalid signature is rejected, and the engine falls back. This is the correct behavior — it's not a vulnerability. But it does mean an attacker who can serve configs can deny new ones.
+
+**Mitigation**: pin the last-known-good config in Storage and apply it if the fetched one fails verification.
+
+---
+
+## Deployment workflow
+
+The canonical flow for signed remote configs:
+
+```
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│ Developer    │   │ CI           │   │ CDN          │   │ User device  │
+│ edits json   │──▶│ signs json   │──▶│ serves json  │──▶│ verifies     │
+└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
+```
+
+### Example GitHub Actions workflow
+
+```yaml
+name: Deploy experiments
+on:
+  push:
+    paths: ['experiments.json']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install variantlab CLI
+        run: npm install -g @variantlab/cli
+
+      - name: Validate config
+        run: variantlab validate experiments.json
+
+      - name: Sign config
+        run: variantlab sign experiments.json --out signed.json
+        env:
+          VARIANTLAB_HMAC_KEY: ${{ secrets.VARIANTLAB_HMAC_KEY }}
+
+      - name: Upload to S3
+        run: aws s3 cp signed.json s3://config.example.com/experiments.json
+          --cache-control "max-age=60"
+```
+
+### CDN cache control
+
+Signed configs should have a short cache TTL (e.g., 60s) so that config updates propagate quickly. The engine's `pollInterval` should match or be slightly longer.
+
+---
+
+## Cost of signing
+
+- **Bundle size**: ~300 bytes (Web Crypto API has no bundle cost; we only ship the canonicalizer and the verify wrapper)
+- **Runtime**: HMAC verification takes ~1 ms on a modern device
+- **Build time**: Signing takes < 100 ms
+
+Signing is cheap. There's no reason not to turn it on for production remote configs.
+
+---
+
+## See also
+
+- [`SECURITY.md`](../../SECURITY.md) — threat model
+- [`config-format.md`](../design/config-format.md) — the `signature` field
+- [`API.md`](../../API.md) — `signConfig`, `verifySignature`
+- [RFC 8785 — JSON Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785)